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PREFACE 


This manual describes the C programming language as 
implemented under Multics. The language is described by noting 
variations from a baseline version of C. The reader is assumed 
to be familiar with C. This manual is not a language 
specification, nor is it intended as a tutorial document. 


Braces { } in this manual are used to enclose information 
from which the user must make a choice. 


The following conventions are used to indicate the relative 
levels of topic headings used in this manual: 


Level Format 
1 (highest ALL CAPITAL LETTERS, UNDERLINED 
2 Initial Capital Letters, Underlined 
3 ALL CAPITAL LETTERS, NOT UNDERLINED 
4 Initial Capital Letters, Not Underlined 


USER COMMENTS FORMS are included at the back of this manual. These forms are to be used to record 
any corrections, changes, or additions that will make this manual more useful. 


Honeywell Bull disclaims the implied warranties of merchantability and fitness for a particular 
purpose and makes no express warranties except as may be stated in its written agreement with 
and for its customer. 

In no event is Honeywell Bull liable to anyone for any indirect, special or consequential 
damages. The information and specifications in this document are subject to change without 


notice. Consult your Honeywell Bull Marketing Representative for product or service 
availability. 


Copyright © Honeywell Bull Inc., 1987 File No.: 1L23 HH07-01 


SIGNIFICANT CHANGES IN HH07-01 


Appendix B, "C Environment Support Commands" is new and the 


following RUN-TIME ROUTINES (Section 4) are either new or 


updated. 


The unmarked items are "new" and the updates are noted 
as "update." 


access 
abort 
alarm 


acctima 
StS ta 
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clock 


ctime (update) 
drand48 


exec] 
execle 
execv 
execve 
execlp 
fentl 
fstat 


getcwd 
getenv 
getgid 
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getopt 
getpid 
getuid 
gmt ime 
loctl 

link © 


' localtime 


perror 
rand 
sleep 
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srand 
stat 
strtok 
strtol 
strtod 
swab 


sys_errlist 


syS_nerr. 
times 
tzset 
ulimit 
utime 
varargs 
vprintf 


HHO07-01 


CONTENTS 
Page 
SECTION 1 PNT RODUCT TON 625656 0505 ae Oe OAs SE OS Berens 1-1 


Definition of Baseline Ci se. Se el we 6 are aN a eee ae l- 
Contents of This Mari Wied Biscdsa es sae onwi oa oe ws es ee ewe etd Severe 1 


a 
_ 


SECTION 2 IMPLEMENTATION OF THE  & LANGUAGE. eseereeveeeeeoeeee 


hex1¢al “Conventions: (270i. dae eee ee See eee oasbie meses 
| Hardware: Character iSt iC 6 6s oe 'esle eb ob ee ais eie-w aed woe ese oes 
What "SS 11l o- Name 2 oo as Ges aise tacvrea ee oes ewe Se he. wok we oS 
CONVEPS1 ONS 6's 6:6 6-5 ese wise ae Sane Wa wis w 8 Se eb ale Boeeews Soe aes 
CharacterS and INtegerS..ccccccccccccsccccssvesssscsseses 
PIOGE -BNE: DOWD GS os ecss: Ss, aeolian Woe! a Sila ue G0e an ew ho Sr ei eae eras ke 
AGGLLAVe: Operators sé oiiw wis cow w crs orw Sethe weer ae ee aw oo ea ole ee 
HILL (OPSrator sig wide ada Gehl os ee Beha Gia ek oes wees o wree eer es 
DECTAF AL TONS is :45y-cu.0:% E40 OG Sle Wie be ave dra alee asia eee se eS 
Structure and Union DeclarationsS.....ccccccccccccccccces 
TYPES “REV UST ECO 6 coo osenig 4k ee lae'e Ged Sv ware tee Red WO Ore ave were sie aie seas 
Structures and “UNIONS 3\6 i046 6 6 oie 6 5446 HE Ble eS eels wale bes 
Explicit Pointer CONVETrS1ONS 6.6 0.0% 6040 6a ws s0 5 0.98 50% waa 
C.Program-POFTEDI LECY & é 65-0. eae core w Ski w Gilas aun eres. 6 Wie SUS. ave wees 
Size: Of. ‘Data TYPGS sods 64 60045 50.60 h-09 6 wee NaN wwe eereeees 
Structures “and UNIONS 6.06 cs cdi ae a wines. Coe eed OHS Sew bee 
Bit Pl ClO gcc i0ece a arate ¢ aa Wa wee a Ow Wie ecs & OSE CER eee 
POIUNC CS oe ios wee eon 5 oc aaa Se Brac wrere OO AS ROSS OSS Ea eae se 
The: Null Pointer Values « <os.0:96 0.0 0:0:0-e eee wee Sd ore 90 wes Oe ws 
System Calls and the Runtime Library... ..c.ccccccsccccece 


! It 
“INI ON OT ONE & WW WW FW W WN DDD HH 


oak ded RR ee era 


Ww ee ee ieee 


! 
jw! 


SECTION 3 INVOKING THE C COMPILER... .ccccccccccccccccccce 


Vv ; HH07-01 


CONTENTS 
Page 


SECTION 4 THE C STANDARD Ly LL BRARY. ois o:0-el Glen w' oe ewe © Sie wee oOo are 4-] 


C Support of Multics File Types... ..ccccccccccvssessecceese 4-14 
Subroutines and Libraries... sss s66s suave deer ene cess eeces, 4°15 
TrADS and SiQNOlSs ¢ ako eek wha ele eh eae Cae ee eweeee S746 
Error ROtUurnSuc. 46066 08 5h denies Peewee wae hese ceases 4228 
Reporting ErrorS Vid ErrnO..ccssessecsvcescessecssesceese 4-18 
UN DR: BRrOrs so bc oon s Sowa. Sct aks CA RRR OSE Mensa 2516 
RUN=TIMe ROULCINGS 606 5 Swed eens See wet os es ee ws Sa eeetewer “SHZ2 
SDOLE 6s SS ial de CWE re wee Wee Sb oRS Oke aaeawees, T=Z3 


OS ik cee 6 ese aa ee Swe aw hae Se Wie or Sa Sw We ts ae eee 4-24 
BCCOSS oy bisa are GS oR S46 S EES TES SSS Dewees. 2525 
ACOSé chases es betwee ea es eee eee en twheceaawa. “£=26 
SLOT bs 6 Gas ke ES SEAR ES OMAR SCO ew ea. Te Z7 
ASCEIMG 6 Va bw cee swe Wee We Bee bee Meese awe eee: 2528 
ASIN +566 oa ee eA hee eaee tee eek e swteeamkeawee. S250 
SCAN esciaie ten 6656 bes eww ee bane ot inane eeees. “Sl 
ACAN2 56:5 sis os SS ewe MEG Se CEN eke eee ee Cees Ce eet eee. AHS2 
SCL sab bes 86 ie CORRE NOE OES EWE Owe Rae Oe. “2FS3 
QtO1 aac Gra vesies cus esd vee ee Ween e Se eee Geese eee. AS Oe 
EO iS es eS OS RO ee Oe EG CA Ee ee weesateee, “4735 
Ca@lIOC 2. fe Pie 8 SENS oe eee awe ee ee een eeensta nee ea “4536 
COL 246 lesen eee Osawa Se eaere tee eee see etan (257 
ClEareOr lies es b6G 6 we heen deal ee ee Soe wAw eee eee eeawers, 2238 
ClOC Cie se eae wt Sed ooo eee ON SOO a ee Cea asaeewes “S=39 
ClOS6s 5 bia eee eatin eo be ee howe ee maeseweteeawe: 22740 
COS i ci Aisa 5 ois SS ais eh eh ee SS eA ORCS BOS eae, Sl 
COS is ike 5-6 Sone Wa ESAS AN CESSES ARES SSE eae: 2eZ 
Creat is 64454 bee wel See 6 aS So 55o4S OOS See eRe oueeeweees.. BERS 
CUAMO ib ioe ee hse Cha ae Se eae ta neiae weer ees esenewae (2748 
COPANO SG Gio sok orl oh Se Sse oe a ae ee baw ee eee eee. “2486 
COVE 6s GiS CSAS ESUWS SES EO SNS SOR Ueeewsweees. L549 
OPT 66bo iia eee Se OO oe REEMA SEER OES eeweeeaca (2°50 
CROC ces oe ae SA NEN Set eee eA eeeeenewae 7425) 


CROC LC eg oie ie ele wee w Soe Oe Sees Sa hw Sa eee haw ewe. 14553 
CXC] Ds oo e6 6 ew aes OOS UA A ewe eeawte see iwws ~4=59 
CX COV 5 use eeu Sh aes eons bbb Oe Oe aw Ree Sew aweeesee. S207 
CXCCV 6 sici-b6 6 5 6a ad SEWERS 156456 KShE Renewed 4-59 
CXOCVD 665.466 SHES RAG EROS hee Se Swaeteuweeesteee “F=bL 


CE Bi We eS e sore] we besa cae aS ate a areae Sle ease ee Siew ewe alte 4-63 
EXPe cece ever escesesesescessecsessesesscessessesesseces 4-64 
PADS 2 cb 6.56.4 Gi lee ee OR CASO OOS WEA We ORS 4-65 
PCIOSEs 66 See Ss Sei eee ws ON Dee eeeeeieae toes. C966 
PCRE 146 66s oie ales ae RSS 6 64 ss ee Ee eh ew eee eS ees s- AH67 
BOVE cccies 6 0 0 oN Oh OO Wa I EEN WERE 4569 
FAODEN roi bois eos Gh CCRC SOR ee ee OREECE WS COR eV eae 770 
COOP 6 sas bale bn Siew do Cae ees es EGS Eee tee URE 


vi HH07-01 


CONTENTS 
Page 


POLPOL b0.< é.8.s/age SNS oo ew ale ore andceserureteiaiece a twevasecews “STZ 
EEUSH oe Sevk owes we eatecs SiR w ies Slecee ee ee re ee ee ewewe, = 713 
EGCtC i. 4.6.6 Raw ees Terr rere Te ib bsetwe ee eeaewowwes, “274 
LOCUS .4.5%0s58's Goh ware © Che ee Sel s ROO S'S Sweetest emeaeeeee “SEO 


fiieno. eeeveveeee ee eeeeVeereeeeeeeeeeseseeeeeseseeseeeeteee @ 4-76 
floor. eeeeeoeeeoeeeoeneeov7eeeeoeeseeesvseeeeoeeeeoeeestneesetmpnseseeeee @ 4-77 
fmod. eeeesveseeeeseseeseeeaeeeseeseseestseeeeeeeeeesteeoeseeeeesteeee 4-78 


PODCM see so eb ecksaveiere Sie a EEN CNG es OSes toro 
Pprintl...<6cuks ere eT Tee ee ee ee Crisceweeeaes, 54-60 
POUL CS oe sa. ties oa sures Serpe ea orate ear wtore ae avele wears cseses  €=85 
PPUtS oo cise ses wewea ei e0% Pere ree ra re CERES Re “2-86 
bib gt. (o Para eer te ae ee ere Sai aie 'a ay mreousev ae iCebet eek ie eaeswn. 2-07 
t EV OS Sosy ausleleat dees G8 wee Teer ee Tr ee ee ee ae (ieemasec 4°88 
EYCODGN } 6.0 o6:6-6.6: 60505 44S 3-6 les Miia toieiweseecereawae, “2589 
PV OLD eos bn 8 SSG REA ee ee re are er rer eye eee oo 
TSCANE . sss cece ee ee ee er ee ae eee ae 
TSE io 5s i edn Se 66 See ee eae aS ee eee er ee ee ee cee) «| 
EWE LE Cs ieee eeereaseas bie eee adie Se MOSES RE SOR eee Hoe 
CV Cw nies 00.0 08ide ce Soe 6-0 Sle Hb 00: w 628 WS 06 SS SOT SNS COs 4-99 
GCOCC Us 6d ws 0:bee Hie we ORO oN aiew ati e eee eoeee 4-100 
GOLCNEE 65.0 6 ered Swed ee hee oe eau Veke Ge eee wees “A> L02 
GEL CWA 65 rise oe as 6 ee So os Se ws OS we ee eee E102 
GEE CIY oe é0. sow als Sele a one Sw ek RS ee ee eae aw 8 ose Ss - 4-103 
GOtGQidecssesaes er Sheen Ge rexerep aera piste bebe SCictineeatestea: S=104 
GOLIOGI 6 ooo here Os Gen eee eee Cee weeaweaeee ess 22105 
GCLODE «aw 4 aobireld  ec eRe eae wee Se Suseeseesvaseeee:. “47106 
Gt pid nh Gis otsi tues nuues ee re eee re ee ee ee 4-109 
GOUS 6 e600 hohe S68 0.66. OS CNR ECME TS OOS WE RRO OSS SS 4-110 
GOlUId s Ss tices eee etesaas re re ee ee ere ere mee ae be ie 
COC 65. 055 RGD OR oO RERA ETE EKO -tttesecieasewseee. “C7412 
CMU IMG 60-65 0:6 6% 6.6aw eens 'Mkbiibseetws hansasamnesaess £- LES 
HY DOt 6 65:56:55 s Sak Oe ORS Oe wh Reece ewes ewes “2-115 
ROCCE oon aati by aera %. ate eae ea ew enw oo ees Saree ‘peewee. L165 
PSL NUM sai ea os oso we OS Ee see th oe bee eens ee eee . 4=122 
AS AlN Gs oss ce ewe ole OS ow oo 8 wre ee ee eee 4-123 
PSASC 15 55.06.55 4 SA SAIS R KES 4S Se OES NER eas. <e-12¢ 
USACLY soise-e%s ooo deees sew eve paw ae es detente tabewesenenece, t= 125 
PSCNCE 1 ccc ww. kia swe ia eee es os ew eacnae cua, 42226 
DSG1G1 G45 Beers SUE RS ERR E SSS SOR RAK SS ele SA OAS 4-127 
LSLOWES. . eee eee cece rere e ence cece ence ce cccecececens 4-128 
ISPFiNt.rcsececeesocreceee éacecos Mitek echieosawsecsaee Se lZ9 
ISPUNCE.... cece eee eee eeeecece re i¢oveseeceness @7130 
VSSDACE is 66 oS ws aia bs POOR eb eNeee eked ESS. 
LSUDDEL 666 Sse sd dete se Saw eee ew ess 'VMGkiseieweres: Sebo2 
USXGIGI U4 es sae saeseeees ere ee ee Ke Mech ae sates, “eas s 


Kill. wccccenccccscssesocnsesseenesesesecscceeicececs 4-134 


LGEXPsscsescevsaces ee ccecccvecs ee 4-135 


vii HHO7-01 


CONTENTS 
Page 


link. eseeeaoee0eveseeeeeeseeseseeeetrmpeensteeeereeeeeteeeeeweesrteeereeneeense 4-136 
localtime eeceseeeHteee¢?eesteense8e28e207e0282880288028080808080R2 802082080232 808080808086 4-138 
log. eeoeesenovoeeseeeseseseeoaeseeoeeeseesseeeeteeeeeeeeeeweeeeeseeeet 8 4-140 


TOGI0 Gb.esateaeree eee Saka ete tea PEEeeoeneeecaeeeacesa: ~4514) 
FONG) MD c:c3:S-oe wa wae Ae arose eee eae ea wean emesine,. S142 
Mal LOC 5 tshiow ee eWwiea Maw eee eee eee eee ee eee eee 2145 
MEMCCDY -cceneeeccecereseeesnesessessesesesesesseesecs 4-144 
MOMENT sid 4-4 ob b o-o5 5k SS SRN eee eR eeeee. 22046 
MOMCMP, wcccccscccesseccccscsccesevssccessccesecesees§ 4-147 
MOMCDY oe. 5 0.6.06 6 9 0e ee wane O 0 A 6S OS OSA eee ewes 47149 
WEMS OCs 44.0 sis 6S Wow WOT 5S Ow he ae ee Eee ee eae. ALOU 
MEE CMD si0 56 065 SHO SO GORE EWES SES OC A RSS eee. SR LSL 
MOOT ish. 6 whe REORDER SO RERGREMO SS COR Ra eee sicee, SS15Z 
ODO 606605 0S ol Ba See we ie Se eS Wee oa Cw Ses Ka eee es ZH LOS 
DOP lOl ss cia tn se fabs Sah S4G CCA Re Shae ie eee aewe “ELS 
DOW 6 6:55 66 LS OK MAAN DASE CASS EURO RU EEDIGENGD EG OS ~S= 156 
DOINCL 64. 6k4 ae S we eho owe owe a eee Nee ek ewes “ER L57 
PUCC £6 55 58S os OES OIACSS RON eee ee eeeeeeeewee B2—IS6 
DULCN OY 0.0,4:6% 4.9 6 oN oo EG NE WEG Nea OOS Ree eeeee- “SLO 
DUCSS ibaa sow sowie S 0G eee weeenaneeee: VERTIGO 
DUE Wis cine cts ac kavie eee ea buloee ee wee tes anieaeeeeesetawes ‘2162 
FONG 6 i chi wwe ON OSES TSS WE eeeeneeweaee 42162 
POA 6 bee MEwC Sie we CORR OREO ORES ARSE eeeceeee “S163 
FOAL IOC y uo e ots Nass ee ae OE OOS BOSS ORS Baa eee. “E164 
SDP Kies oie caw Ossi bow ie OCS RSAC Rese ieee —F=165 
SCANT esis sae. ae ACe-0-e 0s 8a WA Ao REO Ree eae ewes. 24266 
SOC DUNE ye wine Hace eae eae See RAS 6 FE Se EOS ewe ewes 2167 
SOU ND 6.5 6s Go Kw eves susie Slew Sb: oe ASSO SS ee wee waeeewen “27166 
Sila lc 6 <b0-a.6e se sew eekaw sd tete Gene we eee eee wae, “A L69 
SiMe G86 Skee ae ae Os OOH ESSE eestor, “A=172 
SAN s.63: wee oe Seek RCC SRG Oe ota sae Seweowoneetan, SL73 
SLOCD cs 6505 biases ow OSG SEES AI ECS eee ee ewe “S174 
SDPANEL 6.65.06 eGo ors ow Ree ae oe SoS ee ee eee awwwe, 47> L729 
SOE 5666S e646 OFS CSE PERO e wr etiees aoe ese ate Sci 76 
SLANG 66 $606 6 ORS O RAN EE OOS EOS NEWS Dee eewewnee,, PAHL77 
SSCANL <.6:4. beers As wie G56 bs WADE OES eee eee Haweess.. 2HL78 
SE Eo okies a ece ere ese Si ace Wm we iO eta ele 05s Ae ee ike Sloe e wee “S=17o 
SEV COL 6s oid wes sia ie bee ws Ke OES Se eee eee eeees -2— LE) 
SELON oi45 644408 aw 60 se ete sieht erssae eae ueeweeeses “24782 
STTCMP. cccccccvccssvccsesssevessesccscesccesesescene 4-183 
SELCDY vee sie Siei see e Pts kis eee eaweeaueewea ase 3Ee Les 
STTCSPNecvenccsvesnccesesesesvaevcssecssseressecesece 4-185 
SUP LON 666 604Gb Sew le Oe Oe A646 OS OEE Sew Vawewéa 4=186 
SULACAC 6s er CN Eo 60s COONS OS 5G OS Oe Ee Oenoawes: 25167 
SEPNENMD vscciaes Kb se 64 Oo sO SORE Cee we ete eee eee ~2e1L68 
SU ENCDY 066s K.48. 6 b)0-65b.5 5s OO AAW AROSE Ses Oe eee eas. “£5169 
SEPDDEK 5 oi 556-4 6 ek TERR SDA AAS iOS Sees eeeaseee, 2°190 


Vili. HH07-01 


CONTENTS 


SEL ECAE so ee ok SR ORE RESIS EEE EEG Oe OS OE SSS 
ih ak] 0) 6 aoe ee ee er eee erg are a ee er ae eee eee ee eee 
cap ee ad 2 | a ee ee ea eae a Pee ree eee ee ae ea 
SEY CO ese eek Sao oe SS OE OWS a wee a SA 
SEP EO ecto 6i2eis ee eee S16 S ee OSES SOUL ORS biel whee eS 
SS Wk Doses aos WS 5a a www ea oases raw esse Sah aces 0sE, Sse wt aw ata a er eee 
SV SE OM dco o eb © io hw 59048 Re: Www Wore © e leeterel erase Gate a oe eos 
SVS. OPT 11S be iin heb are ose e Se seeres 
SYS NePrr occas 


TN 6 ote ea a elk We OR Oe ee Be BOR OWS Ne 


TAT g ase igre Saar ER Bo Roe See Se OW ae ee 6 we Ow SIS 
BLANC ss cs-o Satsang wake BS eS Wien cah wog  Rate Se 
EAMOS oo ocs ores ars Sie hoe Soe BEE oe SSSR SSE SEES eS 
EMPNAM. cece rovcecsesneersesevevvecevesesecssesessenes 
EOOSC 11 Sa cr wert he Soh enw we aS SS See Se 
£6 LOWEY 66 86-5.-6 6 6 ols OES ees Sa ea ee 
—COLOWED osiir 660 665 FOC 6S 0 o's CSS e SSS e SSS KC ONE w eos 
COUPPEL? . ar wcccc sarees errsereerevsccessesnersceseses 
_ROUDDEOT 6s 0066 6 o S100 0 Wie 008 6 OC 8 Eee te 6 oir we eb ee wee 


EZSCE éws-s-5 oe 


1B || Ey ee memo ae eo Ee ee eee ee eee a eee 


eeseeoeseeseeseteeseeeeeeeeeeteesteeeeseeseset eee too & @ & 


UNGETC. corer vccvvccvcnvveceseeverseseveseseseseseves 
MEL FT as oo a ese estate Se) Beebe raw) wha da eo eee a eee RE 
TEE AMC iia ca sdeeiten'o te OS a ow ee awe eS ew Oe OR KS OED RS OS 
VALOIS i e.5 4 oes here Wee ore owe Boos So Se eww Ee eo ie eee one 


VDFINED,- VEPrINel | VSPPINEE 6 ie 6:45.65 bs ww eiew 4S 6 4 Soe Be 


WE TES Coos tae eee we Ee DW ee Eee Ree 


APPENDIX A C COMPILER DIAGNOSTIC MESSAGES.......ccccccces 


APPENDIX B C ENVIRONMENT SUPPORT COMMANDS.....cceccccsece 


TOU CI 6 ivgee ea tee ae Bae ew ae aw ee A ee 


ONV ec e eee eceseceeneevreeserdeneesseeseseceseecessceseecs 


Page 


4-191 
4-192 
4-193 
4-194 
4-195 
4-196 
4-197 
4-198 
4-199 
4-200 
4-201 
4-202 
4-203 
4-205 
4-206 
4-207 
4-208 
4-209 
4-210 
4-211 
4-212 
4-213 
4-214 
4-215 
4-216 
4-219 
4-221 


TABLES 


Multics C Standard Library (Sorted by Name)......... 
Multics C Routines (Sorted by Function Group)....... 
C-Rout ines Not: ‘Supported secs. 6.0 iia 6 ess woe ww es weeks 
Multics Trap Support of UNIX Signals.......cceceecees 
Software-Generated SignalS.....ccccvecccccccccccsoes 


C Compiler DiagnoStic MeSSAgeS.....ccccccvccccssssees 


ix 


Page 


4-2 
4-7 
4-ll 


HH07-01 


Section 1 


INTRODUCTION 


C is a general-purpose, low-level programming language. It 
was developed under a UNIX* operating system but is now available 
for use with a number of computers and operating systems. 


s s 
mms wre Tlanewriiaran ae 


This manual describes the C programming language as 
implemented on Multics release 12.1. he language is described 
by noting variations from a baseline version of C. 


The reader is assumed to be familiar with C and Multics. 
This manual is not a complete reference document, nor is it 
intended as a tutorial document. 

DEFINITION OF BASELINE C 


The version of C used in this manual as the baseline for 
comparison is described in: 


UNIX System V Release 2.0 Programming Guide 
Published by AT&T April 1984 


‘The phrase baseline C refers to that version of C. You are 
assumed to have a copy of the UNIX operating system book on hand 
when you refer to this manual. 


*UNIX 1S a registered Trademark of AT&T. 
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CONTENTS OF THIS MANUAL 
The rest of this manual is organized as follows: 


Section 2 notes variations in the Multics implementation of 
the C language. 


Section 3 describes the command available for invoking the C 
compiler under the Multics environment. 


Section 4 lists the C standard library of run-time routines. 
Appendix A lists the C compiler diagnostic messages. 
Appendix B lists the C environment support commands. 


A glossary defines terms for a UNIX operating system, C, and 
Multics. 
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Section 2 


IMPLEMENTATION OF 
THE C LANGUAGE 


This section lists variations from the baseline C as 
described in the UNIX System Programming Guide (refer to 
Section 1). 

This section contains only statements of variations. If a 
feature is not described in this section, it is fully supported 
by the C compiler, and behaves exactly the same as in baseline C. 
LEXICAL CONVENTIONS [2] 


The following variations on baseline C lexical conventions 
exist in Multics C. 


Hardware Characteristics 


The size of C data types are: 


Data Type Size (bits) 
char | 9 
unsigned char 9 
int 36 
unsigned int . 36 
short 36 
long 72 
unsigned long 72 
float . 36 


double : 72 
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WHAT'S IN A NAME? 


The C compiler supports all arithmetic types. C data types 
are described below. 


A character variable (char) is a one-byte, signed binary 
integer consisting of eight significant bits and a high-order 
Sign bit. It is always byte-aligned. Use the signed character 
data type for integer data with a domain of -512 to 511 (at 
most). 


An unsigned character variable (unsigned char) is a one-byte, 
unsigned binary integer consisting of nine significant bits. It 
is never negative and always byte-aligned. 


An integer variable (int) is a four-byte, signed binary 
integer consisting of 35 significant bits and a high-order sign 
bit. It is always word-aligned. This is the default data type 
for any variable. 


An unsigned integer variable (unsigned int) is a four-byte, 
unsigned binary integer consisting of 36 significant bits. It is 
never negative and always word-aligned. 


A long variable (long) is an eight-byte, signed binary 
integer consisting of 71 significant bits and a high-order sign 
bit. It is always double-word aligned. 


An unsigned long variable (unsigned long) is an eight-byte 
unsigned binary integer consisting of 72 significant bits. It is 
always positive and always double-word aligned. 


A floating-point variable (float) is a four-byte, 
word-aligned, signed real number. It can contain a value in the 
approximate range 1.0E-38 to 1.0E+38, with up to seven digits of 
precision. 


A double-precision variable (double) is an eight-byte, 
double-word-aligned, signed real number. It can contain a value 
in the approximate range 1.0E-38 to 1.0E+38, with up to 16 digits 
of precision. 


CONVERSIONS 


The following variations on baseline C operand conversion 
exist in Multics C. 


Characters and Integers 


The C compiler performs sign extension on characters and on 
unsigned characters on asSignment. Character variables range in 
value from -256 to 255, and unsigned characters range in value 
from 0 to 512. 
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Float and Double 


The C compiler converts a double-precision variable to a 
floating-point variable by truncation. 


Additive Operators 


When adding or subtracting from pointers, be careful not to 
exceed segment bounds. When subtracting two pointers, the data 
being pointed to should be in the same segment or the result may 
be meaningless. 


Shift Operators 


When a right shift is performed on a signed quantity, the 
Sign is propagated. For instance, in the expression El>>E2, 
where El is a Signed quantity, the vacated bit positions are 
filled by a copy of the sign bit. 


When.a right shift is performed on an unsigned quantity, 
vacated bit positions are filled with zeros. 


DECLARATIONS 


The Multics implementation of C does not use register 
variables. 


All "static"™ functions must be declared before their first 
use. 


Structure and Union Declarations 

The C compiler only recognizes integer fields. The compiler 
does not initialize structures containing bit fields. The 
compiler assigns bit fields left to right within the word. 
TYPES REVISITED 


The following variations on baseline C. types exist in 
Multics C. 


Structures and Unions 


Multics C does not allow phe passing of structures or unions 
to or from functions. 


Explicit Pointer Conversions 
A pointer-to-long or a long-to-pointer conversion simply 


moves data between the two variables. A pointer-to-int 
conversion moves only the low-order bits of the pointer. 
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C PROGRAM PORTABILITY 


There is no guarantee that a program written in C on one 
system will port easily to another system. Even when the 
programmer has been careful to write the program with portability 
in mind, problems may be caused by differences in the target- 
machine hardware or differences between the source and the target 
compiler. 


The following is a discussion of the possible problems that 
may occur when porting C applications to Multics. It is assumed 
that most of the programs that are to be ported will have been 
written under a UNIX operating system on the VAX* or PDP** series 
machines. 


Size of Data Types 


A program may need to know the size of a particular data 
type. If this is hardcoded into the program, the code will not 
be portable if the data type sizes between the two machines 
differ. For example, a program may use the maximum size of an 
int in an expression as follows: 


#define MAXINT 32767 /* largest int on a machine with a 16 bit int */ 


if (y == MAXINT) ...s0e 


This code could cause incorrect results on Multics. Multics 
has a 36-bit integer so the value of MAXINT is not the maximum 
integer size on the Multics hardware. The following code would 
correct the situation: 

#define MAXINT ((int) (((unsigned ) - 1) >> 1)) 


The following examples illustrate nonportable and portable 
ways of coding word definitions: 


Nonportable Example: 


#define word 4 /* hardcoded number of bytes in an integer*/ 


Portable Example: 


#define word sizeof(int) | 


*VAX 11/780 is a trademark of Digital Equipment Corporation. 


**PDP-11 and PDP-7 are trademarks of Digital Equipment 
Corporation. 
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Structures and Unions 


Structures or unions cannot be passed to functions, nor can 
functions return either type. 


Bit Fields 


Multics bit fields may not be any data type other than 
integers or unsigned integers. However, various other compilers 
allow bit fields to be other than the integers or unsigned 
integers. This may cause portability probiems. 


The order in which the bits are put into memory may cause 
problems. The Kernighan and Ritchie C specification does not 
indicate the order in memory of bits in a bit field. 


These problems would become apparent when using masks and 
unions to test bits, since the bits may not be where the tests 
think they are. The following is an example of the type of code 
that may cause problems when ported to Multics: 


union { 


struct { 
7 int num: 4; 
int total: 6; 
int pad: 6; 

} stl; 


struct { 
int word; 
} st2; 

} extract; 


In the above example, st2 is used to extract information from 
stl. The order of bits laid down in bit field determines the 
value of extract.st.word. 


Pointers 


One of the most common causes of nonportable code is the 
casting of pointers to integers. In most machines, pointers and 
integers are the same size. The programmer can then easily put 
pointers into integers with no loss of data. This is very common 
when returning pointers from functions. 


The return value of a function is by default an integer. 
Since in most machines pointers and integers are the same size, 
it 1s quite easy to return a pointer from a function uSing the 
default return size of integer. This does not work on Multics 
because pointers are larger than integers. 
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To fix the problem, the Multics C programmer must define 
these functions as returning a long or a pointer. While 
returning a pointer in a long is allowed, it is not recommended. 


The following code samples illustrate nonportable and 
portable cases of returning a pointer as an integer. 


Nonportable Example: 


my func() /* function returns an int as default */ 
int *p; /* a pointer to an int */ 
if (some_test) return (p); /* returns a poitner in an integer */ 


} 


Portable Example: 


int *my_func() /* function-returns a pointer to an int */ 
int *p; /* a pointer to an int */ 
return (p); /* returns a pointer in a pointer location */ 


The following example shows a nonportable case of an integer 
holding a pointer, followed by a portable fix for Multics: 


Nonportable Example: 


int i; 
struct { 

char y[10]; 

int p; 

} qbert, *t; 
t = &gbert; /* t points to structure */ 
i=t; /* assign pointer to integer */ 
i += 5: /* point to y[5] */ 


Portable Example: 


char *p; 
p= &qbert.y[0]; /* point to start of y */ 
p+=5; /* point to y[5] */ 


Be careful when you use pointers. Pointers on a VAX imple- 
mentation are automatically initialized to zero when the stack 
frame is first allocated. Since zero is also the NULL value, the 
pointers can be used with no pre-initialization. 
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On Multics, you get no automatic initialization, therefore a 
pointer must be explicitly initialized to NULL before it is 
used. The following examples illustrate nonportable and portable 
cases of this: 


Nonportable Example: 
int *y[10]; 


if {(y{3] == NULL).........3 /* no guarantee that y[3] has */ 


/* been assigned to NULL */ 
Portable Example: 


int *y[10] = { NULL, NULL, ....}; 
/* explicitly initialize array of pointers to NULL */ 
The Null Pointer Value 


In most implementations the null pointer value NULL is 
defined to be the int value 0. It is not uncommon to see NULL 


used as a substitute for 0. On Multics the pointer value NULL is 
not 0, but -1]1. 


The following two examples show implementations in which NULL 
is 0, which could cause portability problems; 


Example 1: 
int p; 
if (p == NULL )...... /* use NULL as substitute for zero */ 


Example 2: 
int *t[{10]; 


t[NULL] = 0; /* NULL used as subscript zero */ 
System Calls and the Runtime Library 


Most of the commonly available portable programs have been 
developed on UNIX operating systems, and as such may have calls 
to system routines or runtime routines that are either not 
available on Multics or that have been implemented differently 
(see the documentation of these routines ahead). If this is the 
case it can be dealt with by creating the routine, removing the 
call, or writing a stub. 
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Section 3 


INVOKING THE 
C COMPILER 


This section describes the syntax of the cc command that 
invokes the Multics C compiler. 
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cc 


cc is the Multics C compiler. It accepts as input C source 
programs and/or assembled or compiled programs creating one of 
various output file types. 


SYNTAX: 

cc filenamel, ..., filenamen {-control_args} 
ARGUMENTS; 
filename 


Any file name with a suffix of .c is taken as a C source 
file and is compiled. Any file name suffixed with .alm 
is passed to alm. Any file name suffixed with .cpp is 
passed to the compiler. All other file names are given 
as input to the Linkage Editor. 


CONTROL ARGUMENTS: 
-brief, -bf 


Suppresses printing of messages Stating the current pass 
being performed (default). 


-definition args, -def args 


Specifies define names to be defined or undefined in the 
preprocessor. Where args is a list of define names 
separated by commas with no spaces in the following form: 


-def n,x=2,"y 


The first arg specifies that n is to be defined as 1 in 
the same way as \define n would define n to l. The 
second arg specifies that x is to be given a definition 
of 2, and the last arg specifies that y is to be 
undefined in the preprocessor. 


-include paths, -incl paths 
Specifies the pathnames of include file directories the 
user wishes the preprocessor to look into for include 


files. All arguments up to the next control argument are 
treated as include directory pathnames. 
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-library paths, -1b paths 
Specifies the pathnames of library directories, archives, 
or object files the user wishes the linkage editor to use 
when resolving external references. All arguments up to 
the next control argument are treated as include library 
pathnames. 

-long, -lg 
Specifies that a message shouid be printed specifying the 
completion of each pass of the compiler for each 
specified file name. 

-optimize, -ot 


Runs all compiled files through the optimizer (not 
implemented). 


-output_file pathname, -of pathname 


Forces the output to be placed in the file defined by 
pathname. 


-profile, -pf 
Generates profile information (not implemented). 
-stop_after pass, -spaf pass 


Specifies to cc to stop after the specified pass of the 
compiler. Valid values for pass are: 


preprocessor, pp 


Generates a .cpp file which is the output from the 


preprocessor. 

c 
Generates a .alm file which is an alm source file 
outputted from the C compiler. 

alm 
Generates a .cob file which is the intermediate 
executable file generated from the assembler. This 
file is to be used as input to the Linkage Editor. 

-table, -tb 


Specifies that the compiler should generate symbol table 
information. At the moment this generates a listing via 
the Linkage Editor. 
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Section 4 


THE C STANDARD 
LIBRARY 


This section lists the standard functions and subroutines 
provided with the Multics C compiler. 


The routines provided with the C compiler attempt to present 
C programs with the same interface they would enjoy under a UNIX 
operating system. However, due to the inherent differences in 
the two operating systems, some routines are altered, have 
restrictions not found on UNIX operating systems, or are not 
supported at all. For instance, routines that involve pathnames 
adhere to Multics pathname conventions, not UNIX operating 
systems pathname conventions; the process management and "super 
user" functions are not available. Also excluded are these 
functions: 


Data base 

Multiplexed file 

Multiprecision integer arithmetic 
Plotter I/O 

Packet driver 

Interprocess communication 
Semaphore 

Archive 

X.25. 
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Table 4-1 lists C system functions and subroutines, sorted by 
name; Table 4-2 lists the same functions sorted by function 


group. 


Table 4-3 lists commonly used UNIX operating system 


functions (taken from System V UNIX) not supported under Multics 


Cc. 


The Multics standard C include directories are located in 
>S13p>c_compiler>include. 


Table 4-1. Multics C Standard Library (Sorted by Name) 
(Sheet 1 of 5) 
Function 
Name Function Group 
abort Generate IOT fault Process 
abs Absolute value of integer Mathematical 
access Determine accessibility of file File control 
acos Arc cosine Mathematical 
alarm Schedule signal after interval Process 
alloc Main memory allocation Storage 
asctime Convert time to ASCII System 
asin Arc sin Mathematical 
atan Arc tangent Mathematical 
atan2 Arc tangent Mathematical 
atof Convert ASCII to floating-point String 
atoi Convert ASCII to integer String 
atol Convert ASCII to long integer String 
calloc Main memory allocation Storage 
| ceil Ceiling function Mathematical 
Clearerr File status inquiry Input /output 
Clock Report CPU time used Process 
close Close file File control 
cos Cosine Mathematical 
cosh Hyperbolic cosine Mathematical 
creat Create new file | File control 
ctime Convert date/time to ASCII System 
drand48 Generate uniformly distributed Mathematical 
pseudorandom numbers 
ecvt Output conversion String 
execl Execute a file Process 
execle Execute a file Process 
execlp Execute a file Process 
execv Execute a file Process 
execve Execute a file Process 
execvp Execute a file Process 
exit Terminate a proces | Process | 
t funct 
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fabs 
fclose 
fcntl 
fcvt 
fdopen 
feof 
ferror 
fflush 


fgetc 


fgets 
fileno 
floor 
fmod 
fopen 
fprintf 
fputc 
fputs 
fread 
free 
freopen 
frexp 
fscanf 
fstat 
fwrite 


gcvt 
getc 
getchar 
getcwd 
getenv 
getgid 
getlogin 
getopt 
getpid 
gets 
getr 
getuid 
getw 
gmtime 


hypot 


(Sheet 2 of 5) 


Function 


Absolute value of real value 
Close a file 

Control over open files 

Output conversion 

Open a file 

File status inquiry 

File status inquiry 

Flush a file 

Get character from word or file 
Get string from file 

File status inquiry 

Floor function 

Return remainder function (a/b) 
Open a file 

Formatted output conversion 
Put character or word on file 
Put string on file 

Buffered binary input 

Main memory allocation 

Reopen a file 

Split into mantissa and exponent 
Formatted input conversion 

Get file status 

Buffered binary output 


Output conversion 

Get character from word or file 
Get character from word or file 
Get current working directory 
Get environment name 

Get group ID 

Get login name 

Get option letter from arg 

Get process ID 

Get string from file 

Get record 

Get user ID 

Get word from file 

Convert to Greenwich mean time 


Euclidean distance 


Multics C Standard Library (Sorted by Name) 


Function 
Ground 


Mathematical 
Input /output 
File control 
String 

Input /output 
Input /output 
Input /output 
Input /output 
Input /output 
Input /output 
Input /output 
Mathematical 
Mathematical 
Input /output 
Input /output 
Input /output 
Input /output 
Input /output 
Storage 

Input /output 
Mathematical 
Input/output 
File control 
Input/output 


String 
Input /output 
Input/output 
File control 
Process 
Process 
Process 
String 
Process 
Input /output 
Input/output 
Process 
Input/output 
System 


Mathematical 
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Table 4-1. 
(Sheet 3 of 5) 
Function 

ioctl Control device 
isalnum Character classification 
isalpha Character classification 
isascil Character classification 
isascii8 Character classification 
isatty Get name of terminal 
iscntrl Character classification 
isdigit Character classification 
isgraph Character classification 
islower Character classification 
isprint Character classification 
ispunct Character classification 
isspace Character classification 
isupper Character classification 
isxdigit Character classification 
ldexp Split into mantissa and exponent 
link Link to a file 
localtime Convert date/time to local time 
log Natural logarithm 
logl10 Common logarithm 
longjmp Non-local goto 
malloc Main memory allocator 
memccpy Memory-to-memory copy 
memchr Point to character in memory 
memcmp Compare memory areas 
memcpy Memory-to-memory copy 
memset Initialize memory 
mktemp Make unique file name 
modf Split into mantissa and exponent 
kill Send signal to process 
open Open file 
perror Print system error message 
pow Power function 
printf Formatted output conversion 
putc Put character or word on file 
putchar Put character or word on file 
putr Put record on a file 
puts Put string on file 
putw Put word on file 


Multics C Standard Library (Sorted by Name) 


Function 


Group 


Input/output 
String 
String 
String 
String 
System 
String 
String 
String 
String 
String 
String 
String 
String 
String 


Mathematical 
File control 
System 
Mathematical 
Mathematical 
System 


Storage 
Storage 
Storage 
Storage 
Storage 
Storage 
File control 
Mathematical 


Process 
File control 


System 

Mathematical 
Input/output 
Input /output 
Input/output 
Input /output 
Input/output 
Input /output 
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rand 
read 
reallsoc 
sbrk 
scanf 
setbuf 
setjmp 
sin 
sinh 
sleep 
sprintf 
sqrt 
srand 
sscanf 
stat 
strcat 
strchr 
strcmp 
strcpy 
strcspn 
strien 
strncat 
strncmp 
strncpy 
strpbrk 
strrchr 
strspn 
strtod 


strtok 
strtol 
swab 

system 


sys_errlist 
syS_nerr 


tan 
tanh 
time 
times 
tmpnam 
toascil 
tolower 
toupper 
tzset 
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Function 


Random number generator 
Read from a file 


j Reallocate memory 


Change memory allocation 
Formatted input conversion 
Assign buffering to a file 
Prepare for non-local goto 
Sine 

Hyperbolic sine 

Suspend execution for interval 
Formatted output conversion 
Square root 

Random number generator 
Formatted input conversion 
Get file status 
Character-string concatenation 
First C occurrence 

Compare 

Copy 

Compare length of strings 
Lengtn 

Concatenate N characters 
Compare N characters 

Copy N characters 

Find first S} in S92 

First C occurrence 


Length of Sj substr of S92 chars 
Convert string to double precision 


numbers 

Token separator 

Convert string to long integer 
Swap bytes 

Execute a command line 


Vector of system error messages 
Largest system error message number 


Tangent 
Hyperbolic tangent 

Get time 

Get process times 

Create temporary file name 
Character translation 
Character translation 
Character translation 

Set time zone 


Multics C Standard Library (Sorted by Name) 


Function 
Grcup 


Mathematical 
Input /output 
Storage 


Storage 
Input/output 
Input/output 
system 
Mathematical 
Mathematical 
Process 
Input/output 
Mathematical 
Mathematical 
Input/output 
File control 
String 
String 
String 
String 
String 
String 
String 
String 
String 
String 
String 
String 
String 


String 
String 
String 
System 
System 
System 


Mathematical 
Mathematical 
Process 
Process 
File control 
String 
String 
String 
System 
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ulimit 
ungetc 
unlink 
utime 


varargs 
vprintf 


walt 
write 
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Function 


Get and set user limits 

Push character back into input file 
Remove directory entry 

Set file time stamps 


Handle variable argument list 
Print formatted output of a varargs 
argument list 


Wait for process to terminate 
Write on file 
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Multics C Standard Library (Sorted by Name) 


Function 
Group 


File control 
Input/output 
File control 
File control 


Input/output 
Input/output 


Process 
Input/output 
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(Sheet 1 of 4) 


File control | access 
close 
creat 
fentl 
fstat 
getcwd 
link 
mktemp 
open 
stat 
tmpnam 
ulimit 
unlink 
utime 


Input/output | clearerr 
fclose 
fdopen 
feof 
ferror 
fflush 
fgetc 
fgets 
fileno 
fopen 
fprintf 
fputc 
fputs 
fread 

f reopen 
fscanf 
fwrite 
getc 
getchar 
gets 
getw 
ioctl 
printf 
putc 
putchar 
puts 
putw 
read 
scanf 
setbuf 
sprintf 
sscanf 


Function 


Determine accessibility of file 
Close file 

Create new file 

Control over open files 

Get file status 

Get current working directory 
Link to a file 

Make unique file name 

Open file 

Get file status 

Create name for temporary file 
Get and set user limits 

Remove directory entry 

Set file time stamps 


File status inquiry 

Close a file 

Open a file 

File status inquiry 

File status inquiry 

Flush a file 

Get character from word or file 


e s 
fram f:11 
Get string from fil 


File status inquiry 

Open a file 

Formatted output conversion 
Put character or word on file 
Put string on file 

Buffered binary input 

Reopen a file 

Formatted input conversion 
Buffered binary output 

Get character from word or file 
Get character from word or file 
Get string from file 

Get word from file 

Control device 

Formatted output conversion 
Put character or word on file 
Put character or word on file 
Put string on file 

Put word on file 

Read from file 

Formatted input conversion 
Assign buffering to file 
Formatted output conversion 
Formatted input conversion 
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Input/output 
| (cont.) 
Mathematical 
| 
| 


Process 
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Multics C Routines (Sorted by Function Group) 
(Sheet 2 of 4) 


ungetc 
varargs 
vfprintf 


vsprintf 
write 


abs 
acos 
asin 
atan 
atan2 
ceil 
cos 
cosh 
drand48 


exp 
fabs 
floor 
fmod 
frexp 
hypot 
ldexp 
log 
log10 
modf 
pow 
rand 
sin 
sinh 
sqrt 
srand 
tan 
tanh 


abort 
alarm 
clock 
execl 
execle 
execlp 
execv 
execve 
execvp 


Function 


Push character back into input file 
Handle variable argument list 

Print formatted output of a varargs 
argument list 
Print formatted output of a varargs 
argument list 
Write on file 


Absolute value of integer 
Arc cosine 


Arc sin 


Arc tangent 
Arc tangent 
Ceiling function 


Cosine 


Hyperbolic cosine 
Generate uniformly distributed 


pseudorandom numbers 
Exponential function 
Absolute value of real value 
Floor function 


Return remainder function (a/b) 

Split into mantissa and exponent 
Euclidean distance 
Split into mantissa and exponent 
Natural logarithm 
Common logarithm 

Split into mantissa and exponent 
Power function 


Random number generator 


Sine 


Hyperbolic sine 
Square root 


Random number generator 


Tangent 


Hyperbolic tangent 


Generate IOT fault 
Schedule signal after interval 


Report CPU time used 


Execute 
Execute 
Execute 
Execute 
Execute 
Execute 


a 


a 
a 
a 
a 
a 
e 


file 
file 
file 
file 
file 
file 


| ae | Terminate a process | 
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MOD 400 C Routines (Sorted by Function Group) 
(Sheet 3 of 4) 


Table 4-2. 


Function 


strcspn 


Compare length of strings 


Process getenv Get environment name 

(cont.) getgid Get group ID 
getlogin Get login name 

| getpid ! Get process ID 

getuid Get user ID 
kill Send signal to process 
Signal Catch signal 
time Get time 

Storage alloc Main memory allocation 
calloc Main memory allocation 
free Main memory allocation 
malloc Main memory allocator 
memccpy Memory-to-memory copy 
memchr Point to character in memory 
memcmp Compare memory areas 
memcpy Memory-to-memory copy 
memset Initialize memory 
realloc Reallocate memory 
sbrk Change memory allocation 

| String a641 Convert base-64 ASCII to long 

atof Convert ASCII to floating point 
atoi Convert ASCII to integer 
atol Convert ASCII to long integer 
ecvt Output conversion 
fevt Output conversion 
gcvt Output conversion 
getopt Get option letter from arg 
isalnum Character classification 
isalpha Character classification 
isascii Character classification 
isascii8 Character classification 
iscntrl Character classification 
isdigit Character classification 
isgraph Character classification 
islower Character classification 
isprint Character classification 
ispunct Character classification 
isspace Character classification 
isupper Character classification 
isxdigit Character classification 
Strcat Character-string concatenation 
strchr First C occurrence 
strcmp Compare 
strcpy Copy 
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String 
(cont. ) 


System 


MOD 400 C Routines (Sorted by Function Group) 
(Sheet 4 of 4) 


strlen 
strncat 
strncmp 
strncpy 
strpbrk 
strrchr 
strspn 
strtod 


strtok 
strtol 
swab 
toascii 
toascii8 
tolower 
_tolower 
toupper 
_toupper 


asctime 
ctime 
errno 

gmt ime 
localtime 
longjmp 
perror 
set jmp 
system 
sys_errlist 
sys_nerr 
tzset 


Length 

Concatenate N characters 
Compare N characters 

Copy N characters 

Find first S] in So 

First C occurrence 

Length of Sj substring of S92 
Convert string to double precision 
numbers 

Token separator 

Convert string to long integer 
Swap bytes 

Character conversion 
Character conversion 
Character conversion 
Character conversion 

Character conversion 

Character conversion 


Convert time to ASCII 

Convert date/time to ASCII 
Error message number 

Convert to Greenwich mean time 
Convert date/time to local time 
Non-local goto 

Print system error message 
Prepare for non-local goto 
Execute a command line 

Vector of system error messages 
Largest system error message number 
Set time zone 
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Table 4-3. C Routines Not Supported (Sheet 1 of 4) 


Function 


Convert base-64 ASCII to long 
Program verification 


a641 
assert 


Change memory allocation 
| Binary Search 


ar ee wer Se 8 


chdir Change working directory 


chmod Change mode of file 

chown Change owner 

chroot Change root directory 

ctermid Get terminal ID 

crypt DES encryption 

cuserid Get user ID 

dbminit Data base subroutine 

delete Data base subroutine 

dial Dial external line 

dup Duplicate open file descriptor 
encrypt DES encryption 

edata End of program initialized data location 
end End of program data location 
endgrent Close group file 

endpwent Close password file 


| ene | Equal-names convention 


erf Return error function of arg 
erfc Return l-erf (x) 

errno Error message number 

etext End of program code location 


fetch Data base subroutine 
find file Find a file 

firstkey Data base subroutine 
fork Spawn a new process 


fseek Reposition a file 
ftell Reposition a file 
ftw File tree walk 
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Name Function 


Table 4-3. 


gamma 
getdir 
getegid 
geteuid 
getgrent 
getgrgid 
getgrnam 
getpass 
getpgrp 
getppid 
getpwent 
getpwnam 
getpwuid 
getptcb 
gettcb 
gsignal 


hcreate 
hdestroy 
hsearch 


init_mem 


logname 
lsearch 
lseek 
ltol3 


matherr 
mcl 

mknod 
monitor 
mount 

mpx et al 


nextkey 
nice 
nlist 


C Routines Not Supported (Sheet 2 of 4) 


Log absolute value gamma function 
Get pathname of system directory 
Get effective group ID 

Get effective user ID 

Get group file entry 

Get group file entry 

Get group file entry 

Read password 

Get process group 

Get parent process ID 

Get passwork record entry 

Get password record by login name 
Get password record by user ID 
Get parent TCB 

Get TCB 

Get signal 


Create heap 
Destroy heap 
Search heap 


Initialize memory 


Bessel function: 
Bessel function 
Bessel function 


Convert 3-byte integer to long 
Convert long to base-64 ASCII string 


Long divide 

Long Multiply 

Long remainder 

Login name of user 

Linear search 

Change file currency 

Convert long integer to 3-byte 


nn 


Math routine error handler 

Execute Multics macrocall 

Make node (directory or file) 

Prepare execution profile 

Mount volume 

Create and manipulate multiplexed files 


Data base subroutine 


Change priority of a process | 
Get entries from name list 
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Table 4-3. C Routines Not Supported (Sheet 3 of 4) 


Function 


Stop until signal 
Close a pipe 
Interprocess communication 
Process lock 


popen | Open @ pipe to/from process 
posr Position file record pointer 
profil Execution profile 

pthto6 Convert UNIX pathname to Multics 
ptrace Trace a process 


putpwentry | Write password entry 


qsort Quicker sort 

regcmp Compile regular expression 
regx Execute regular expression 
runl Create new process 

runlp Create new process 

runv Create new process 

runvp Create new process 


same_file | Compare pathnames 


send_sig Send signal to process 
setgid Set group ID 

setgrent Rewind group file 

setkey DES encryption 

setpgrp Set process group 
setprint Set print attribute of stream 
setpwent Rewind password file 
setuid Set user ID 

sgetl Get long numeric 

Sig Signal 

Signal Catch signal 

smopen Open for block read/write 
smread Read block 

smwrit Write block 

sputl Put long numeric 


Sstar_check | Validate star name 
Star_match | Validate and match star name 
star_name List star name matches 


stime Set time 

store Data base subroutine 

stty Set terminal characteristics 
synch Update superblock 
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Table 4-3. 


tdelete 
tell 
tmpfile 
tmpnam 
tsearch 
ttyname 
twalk 
tzname 


C Routines Not Supported (Sheet 4 of 4) 
Function 


Delete tree 

Change file currency 

Create temporary file 
Temporary name ; 

Search tree 

Get name of terminal 

Walk tree 

Get time zone 


ucf defc Create file 
ucf defr Create file 
ucf_ finish | Create file 
ucf_init Create file 


uldiv 
ulrem 
umemchr 
umemcmp 
umemcpy 
umemset 


Long unsigned divide 

Long unsigned remainder 
Point to character in memory 
Compare memory areas 
Memory-to-memory copy 
Initialize memory 


unmount Dismount volume 


yo Bessel function 
yl Bessel function 
yn Bessel function 


C SUPPORT OF MULTICS FILE TYPES 


C supports sequential files with most functions. 


The creat function creates a sequential file. 


Sequential 


processing of pre-existing string-relative files will be compat- 


ible with a UNIX operating system. 
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SUBROUTINES AND LIBRARIES 


C subroutines and libraries include input/output and 
mathematical functions. While these functions are not directly 
callable from C, you can use these functions with include 
statements of the form: 


# include <stdio.h> 
# include <math.h> 


Functions in the math library may return conventional values 
0 or HUGE (largest size precision floating number) when the 
function is undefined for the given arguments or when the value 
is not representable. In these cases, the external variable 
errno is set to the value EDOM or ERANGE,. 


The descriptions of some functions refer to the null pointer 
(NULL). This value will not match that of any legitimate 
pointer, so many functions that return pointers return it, for 
example, to indicate an error. NULL is defined in <stdio.h> as 
(void*)0; you can include your own definition if you are not 
using <stdio.h>. 


The standard I/O package consists of the stdio.h header file 
and a set of functions. The inline macrocalls getc and putc 
handle characters quickly. The macrocalls getchar, putchar, and 
the higher level routines fgetc, fgets, fprintf, fputc, fputs, 
fread, fscanf, fwrite, gets, getw, printf, puts, putw, and scanf 
all use getc and putc; they can be freely intermixed. 


A file with associated buffering is declared to be a pointer 
to a defined type FILE. The fopen function creates certain 
descriptive data for a file and returns a pointer to designate 
the file in all further transactions. Normally, there are three 
open files with constant pointers declared in the "include" file 
and associated with the standard open files: 


stdin -- Standard input file (Multics user_input) 
stdout -- Standard output file (Multics user_output) 
stderr -- Standard error file (Multics error_output). 


An integer constant EOF (-1) is returned when a function 
encounters the end of a file or an error oe the individual 
descriptions for details). 


_ Any application that uses this package must include the 
header file of pertinent macrocall definitions, as follows: 


# include <stdio.h> 
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The functions and constants mentioned in the input/output 
functions are declared in that "include" file and need no further 
declaration. The constants and the following "functions" are 
macrocalls (redeclaration of these names is perilous): 


clearerr 
feof 
fileno 
getc 
getchar 
putc 
putchar. 


TRAPS AND SIGNALS 


Generally, Multics traps are mapped to their UNIX operating 
system equivalents, to provide an emulation of a UNIX operating 
system environment. After catching a signal in a UNIX operating 
system, a program can continue as if the signal had not been sent 
merely by returning from the signal catcher (as opposed to 
calling exit). 


Multics traps will be mapped into UNIX operating system 
Signals as described in Table 4-4. This table shows the Multics 
conditions available to the C user and their corresponding UNIX 
operating system Signal value. 


Table 4-4. Multics Trap Support of 
UNIX Operating System Signals 


UNIX Operating 


Multics Condition System Signal 
sus SIGHUP 
program_interrupt SIGINT 
quit SIGQUIT 
illegal_opcode, illegal_modifier SIGILL 
mme 1 SIGTRAP 
overflow, underflow SIGFPE 
10_error | SiIGBUS 
out_of_bounds SIGSEGV 
command_error, active_function_error SIGSYS 
alrm SIGALRM 


Refer to the Multics Programmer's Reference Manual for a 


description of the Multics conditions. 
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Table 4-5 lists software-generated signals. Note that "pid" 
is the process ID. 


Table 4-5. Software-Generated Signals 


pearing 


Test Signal, always ignored 
Hangup 

Interrupt 

Quit 

Invalid instruction 

Trace trap 

IOT instruction? 

EMT instruction? 
Floating-point exception 

Kill 

Megabus error 

Segmentation violation 

Bad argument to function 
Write to pipe having no readers 
Alarm clock 

Alarm clock (after delta secs) 
Terminate 

User-defined signal 1 
User-defined signal 2 

Death of a child 


wes 


Power-fail restart 


C Calling Sequence 


kill (pid, 0) 

kill (pid, SIGHUP) 
kill (pid, SIGINT) 
kill (pid, SIGQUIT) 
kill (pid, SIGILL) 
kill (pid, SIGTRAP) 
kill (pid, SIGIOT) 
kill (pid, SIGEMT) 
kill (pid, SIGFPE) 
kill (pid, SIGKILL) 
kill (pid, SIGBUS) | 
kill (pid, SIGSEGV) 
kill (pid, SIGSyYS) 
kill (pid, SIGPIPE) 
kill (pid, SIGALRM) 
alarm (delta) 

kill (pid, SIGTERM) | 
kill (pid, SIGUSR1) 
kill (pid, SIGUSR2) 
kill (pid, SIGCLD) 
kill (pid, SIGPWR) 


a 
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*On some processors 


In a UNIX operating system, the interrupt and quit Signals 
are sent to every process in the process group that is not 
ignoring the signal. Processes created to run a command in the 
background (asynchronously) are created with these signals being 
ignored. Processes created to run a command in the foreground 
(synchronously) are created with default handling of these 
Signals unless otherwise specified via the trap command. All 
other processes inherit the handling of these (and all other) 
Signals from their parent. 


On Multics, Signals will be ere and handled by each 
execution unit. If no signal mechanism exists at the current 
execution, the Multics default_error_handler will be invoked. 


(See the Multics Programmer's Reference Manual for a description 
of this handler.) 
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ERROR RETURNS 


Most functions have one or more error returns. An error 
condition is indicated by an otherwise impossible returned 
value. This is almost always -1; the individual descriptions 
specify the details. 


Reporting Errors Via errno 


A UNIX operating system error number is returned in the 
external integer variable errno. The variable errno is not 
cleared on successful calls, so it should be tested only after an 
error has been indicated. 


UNIX Operating System Errors 


All of the possible error numbers are not listed in each 
function description because many errors are possible for most of 
the calls. The following is a complete list of the error 
numbers, manifest constants, and names as defined in <error.h>. 


1 EPERM Not owner. 


In a UNIX operating system, this error typically indicates an 
attempt to modify a file in some way forbidden except to its 
owner or Super-user. 


2 ENOENT No such file or directory. 


This error occurs when a file name is specified and the file 
should exist but does not, or when one of the directories in a 
pathname does not exist. 


3 ESRCH No such process. 


No process can be found corresponding to that specified by 
the process ID in kill. 


4 EINTR Interrupted process. 


An asynchronous signal (such as interrupt or quit), which the 
user has elected to catch, has occurred during a function. If 
execution is resumed after processing the signal, it appears as 
if the interrupted function returned this error condition. This 
iS a UNIX operating system error only; it never occurs in 
Multics. 


5 EIO I/0 error. 


Some physical 1/0 error. This error may in some cases occur 
on a call following the one to which it actually applies. 
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6 ENXIO No such device or address. 

In a UNIX operating system, this occurs when I/O on a special 
file refers to a device that does not exist, or is beyond th=2 
limits of the device. It may also occur when, for example, a 
tape drive is not online or no disk pack is loaded on a drive. 

7 E2BIG Argument list too long. 


An argument list longer than 5120 characters is presented to 
a member of the exec family. 


8 ENOEXEC Exec format error. 

In a UNIX operating system, this occurs when a request is 
made to execute a file that, although it has the appropriate 
access, does not start with a valid magic number. This is a UNIX 
operating system error only; it never occurs in Multics. 

9 EBADF Bad file number. 

A file descriptor refers to no open file, a read request is 
made to a file that is open only for writing, or a write request 
is made to a file that is only open for reading. 

10 ECHILD No children. 


A wait was executed by a. process that has no existing child 
processes; or by a process already waiting for all its children. 


11. EAGAIN No more processes. 


A fork failed because you are not allowed to create any more 
processes. 


12 ENOMEM Not enough memory. 

During an exec, sbrk, or other function, a program asks for 
more space than Multics can supply. This is not a temporary 
condition; the maximum space is a system parameter. 


13 EACCES Permission denied. 


An attempt has been made to access a file to which you have 
insufficient access. | | 


14 EFAULT Bad address. 


On Multics this error is performed by a fault and is not 
available to the user. 
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15 ENOTBLK Block device required. 

In a UNIX operating system this occurs when a nonblock file 
is mentioned where a block device is required; for example, in 
mount. 

16 EBUSY Mount device is busy. 

In a UNIX operating system this occurs when an attempt is 
made to mount a device that is already mounted, or an attempt is 
made to demount a device on which there is an active file (open 
file or current directory). It also occurs if an attempt is made 
to enable accounting when it is already enabled. 

17 EEXIST File already exists. 


An existing file is mentioned in an inappropriate context; 
for example, link. 


18 EXDEV Cross-device link. 


In a UNIX operating system this occurs when a link to a file 
on another device is attempted. 


19 ENODEV No such device. 


An attempt has been made to apply an inappropriate function 
to a device; for example, read a write-only device. 


20 ENOTDIR Not a directory. 


A file is specified where a directory is required, for 
example in a path prefix or as an argument to chdir. 


21 EISDIR Is a directory. 

An attempt has been made to write on a directory. 

22 EINVAL Invalid argument. 

Some invalid argument has occurred; for example, mentioning 
an undefined signal in signal, or kill. This error is also set 
by the mathematical functions. 


23 ENFILE File table overflow. 


The system table of open files is full, and temporarily no 
more opens can be accepted. 


24 EMFILE Too many open files. 


No process can have more than 20 file descriptors open at a 
time. 
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25 ENOTTY Not a typewriter. 

The device is not a terminal. 

26 ETXTBSY Text file busy. 

In a UNIX operating system this occurs when an attempt has 
been made to execute a pure procedure program that is currently 
open for writing (or reading), or an attempt has been made to 
open for writing a pure procedure program that is being executed. 


27 EFBIG File too large. 


In a UNIX operating system this occurs when the size of a 
file exceeds the maximum file size or ULIMIT. 


28 ENOSPC No space left on device. 


During a write to an ordinary file, there is no free space 
left on the device. 


29 ESPIPE Illegal seek. 


In a UNIX operating system this occurs when an lseek has been 
issued to a pipe. 


30 EROFS Read-only file system. 


An attempt was made to modify a file or directory on a device 
mounted read-only; that is, with the write-protect switch set. 


31 EMLINK Too many links. 


In a UNIX operating system this occurs on an attempt to make 
more than the maximum number of links (1000) to a file. 


32 EPIPE Broken pipe. 

In a UNIX operating system this occurs when a write has been 
attempted on a pipe for which there is no process to read the 
data. This condition normally generates a signal; the error is 
returned if the signal is ignored. 

33 EDOM Math argument not in function's domain. 


The argument of a function in the math package is out of the 
domain of the function. 


34 ERANGE Math function's result too large. 


The value of a function in the math package is not 
representable within machine precision. 
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35 ENOMSG No message of desired type. 


An attempt was made to receive a message of a type that does 
not exist on the specified queue. This is a UNIX operating 
system error only; it never occurs in Multics. 


36 EIDRM Identifier removed. 


This error is returned to processes that resume execution due 
to the removal of an identifier from the file system's name 
Space. This is a UNIX operating system error only; it never 
occurs in Multics. 


RUN-TIME ROUTINES 
The rest of this section describes the run-time routines 
(either functions or macrocalls): available under Multics C. The 


descriptions are arranged alphabetically by routine name. Refer 
to Tables 4-1 and 4-2 for a complete list of routines. 
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abort 


abort 
Terminate a C program. 
SYNTAX: 
int abort ( ) 
ARGUMENTS: 
None. 
DESCRIPTION: 
The abort function causes an IOT signal to be sent to its own 
process. The default signal catcher causes program 
termination. 
It is possible for abort to return control if SIGIOT is 


caught or ignored. In this case, the value returned is that 
of the kill function. 
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abs 


Integer absolute value. 
SYNTAX: 


int abs (i) 
int i: 


ARGUMENTS : 
i 

Integer value whose absolute value is to be returned. 
DESCRIPTION: 


The abs function returns the absolute value of its integer 
operand. 


RELATED FUNCTIONS: 
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access 


access 
Determine access rights or existence of a file. 
SYNTAX: 
int access (path, amode) 
char *patnh; 
int amode; 
ARGUMENTS : 
path 
Pointer to a pathname seaming a. file. 


amode 


Bit pattern constructed as a sum of the following: 


04 -- Read 

02 -- Write 

O01 -- Execute (search) 
DESCRIPTION: 


file according to the bit pattern contained in the amode 
argument. 


The file has access checked with respect to the read, write, 
and execute mode bits. 


No access to the file is indicated if the information request 
of the file system returns an error. 


RETURN VALUE: 
If the requested access is permitted, a value of 0 is 
returned. Otherwise, a value of -1 is returned. The 


variable errno is set to indicate a UNIX operating system 
error. 
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acos 


Arc cosine function. 
SYNTAX: 
# include <math.h> 


double acos (x) 
double x; 


ARGUMENTS : 
x 

Double value of the cosine. 
DESCRIPTION: 


The acos function returns the arc cosine in the range 0 to 
pi. 
DIAGNOSTICS: 


Arguments of magnitude greater than 1 cause acos to return 
value 0. 


RELATED FUNCTIONS: 


asin, atan, atan2, cos, sin, tan. 
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alarm 


alarm 


Set a process alarm clock. 
SYNTAX: 


int alarm (sec) 
int sec; 


ARGUMENTS : 
sec 

Number of seconds until alarm. 
DESCRIPTION: 
The alarm function instructs the calling process's alarm 
clock to send the signal SIGALRM to the calling process after 
the number of real-time seconds specified by the sec argument 


have elapsed; see signal. 


Alarm requests are not stacked; successive calls replace the 
calling task's alarm clock. 


If sec is 0, any previously made alarm request is canceled. 
RETURN VALUE: 


The alarm function returns the amount of time, possibly 0, 
previously remaining in the calling process's alarm clock. 


DIAGNOSTICS: 


If alarm is unable to set the alarm clock for any reason, 
errno is set to indicate the reason and -1 is returned. 


RELATED FUNCTIONS: 


Signal. 
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asctime 


asctime 
Convert date and time to ASCII. 
SYNTAX: 
# include <time.h> 
char *asctime (tm) 
struct tm *tm; 
extern long timezone; 
extern int daylight; 
extern char *tzname[2]; 
ARGUMENTS : 
tm 
Time, in military notation. 
DESCRIPTION: 
The asctime function converts the components of the time to 
ASCII and returns a pointer to a 26-character string in the 
following form (all fields have constant width): 
Fri Aug 10 10:24:54 1984\n\0 


The structure declaration from the include file is: 


struct tm { 


int tm_sec; 
int tm_min; 
int tm_hour; 
int tm_mday; 
int tm_mon; 
int tm_year; 
int tm_wday; 
int tm_yday; 
int tm_isdst; 


}; 


These quantities give the time on a 24-hour clock, day of 
month (1-31), month of year (0-11), day of week (Sunday - 0), 
year - 1900, day of year (0-365), and a flag that is nonzero 
if daylight savings time is in effect. 
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asctime 


The external long variable timezone contains the difference, 
in seconds, between GMT and local standard time (in EST, 
timezone is 5*60*60); the external variable daylight is 
nonzero if and only if the standard U.S. daylight savings 
time conversion should be applied. 


If the environment variable TZ is not present, the asctime 
function assumes the local time zone is the same as the 
system time zone. The external variable daylight is set to 
zero in this case. 


If TZ is present, the asctime function uses it to determine 
the local time zone. The value of TZ must be a time zone 
acronym, a time offset, and an optional daylight savings time 
zone acronym. 


@e The time zone acronym is up to four characters long. 

e The time offset represents the difference between 
local time in the designated time zone and GMT. The 
difference is represented by a string of digits with 
an optional leading minus sign (for locations east of 
Greenwich, England) and with an optional trailing .5 
(for locations some odd number of half-hours from 
Greenwich). 


@® The optional daylight savings time zone acronym is up 
to four characters long. 


For example, the setting for Boston would be EST5EDT. 
Setting TZ changes the values of the external variables 
timezone and daylight; in addition, time zone acronyms 
contained in the external variable tzname are set: 
char *tzname[2] = {"EST ", "EDT "}; 
NOTE 


The return values point to static data whose con- 
tents are overwritten by each call. 


RELATED FUNCTIONS: 


ctime, gmtime, localtime, time, tzset; see also the 
list_stz and set_stz commands. , 
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Arc sine function. 
SYNTAX: 
# include <math.h> 


double asin (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value of the sin. 
DESCRIPTION: 


The asin function returns the arc sine in the range 
pi/2. 


DIAGNOSTICS: 


-pi/2 te 


Arguments of magnitude greater than 1 cause asin to return 


value Q. 
RELATED FUNCTIONS: 


acos, atan, atan2, cos, sin, tan. 
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atan 


atan 


Arc tangent function. 
SYNTAX: 
# include <math.h> 


double atan (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value of the tangent. 
DESCRIPTION: 


The atan function returns the arc tangent of x in the range 
-pi/2 to pi/2. 


RELATED FUNCTIONS: 


acos, aSin, atan2, cos, sin, tan. 
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atan2 


atan2 


Arc tangent of y/x. 
SYNTAX: 
# include <math.h> 


double atan2 (y, x) 
double x, y; 


ARGUMENTS ; 
x 


Double-precision value. 


Double-precision value. 
DESCRIPTION: 


The atan2 function returns the arc tangent of y/x in the 
range -pi to pi. 


RELATED FUNCTIONS: 


acos, aSin, atan, cos, sin, tan. 
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atof 


atof 


Converts ASCII to floating point. 
SYNTAX: 


Goubie atof (aptr) 
char *aptr; 


ARGUMENTS ;: 
aptr 
A string of tabs and spaces, then an optional sign, then 
a string of digits optionally containing a decimal point, 
then an optional e or E followed by an optionally signed 
integer. | 
DESCRIPTION: 
The atof function converts a string to floating-point 
representation. The first unrecognized character ends the 
String. 
NOTE 
There are no provisions for overflow. 


RELATED FUNCTIONS: 


atoi, atol, scanf. 
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Converts ASCII to integer. 
SYNTAX: 


int atoi (aptr) 
char *aptr; 


ARGUMENTS : 
aptr 


A string of tabs and spaces, then an optional sign, then 
a string of digits. 


DESCRIPTION: 
The atoi function converts a string to integer 
representation. The first unrecognized character ends the 
string. 
NOTE 
There are no provisions for overflow. 


RELATED FUNCTIONS: 


atof, atol, scanf. 
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atol 


Converts ASCII to long. 
SYNTAX : 


long atof {(aptr) 
char *aptr; 


ARGUMENTS : 
aptr 


A string of tabs and spaces, then an optional sign, then 
a string of digits. 


DESCRIPTION: 
The atol function converts a string to long integer 
representation. The first unrecognized character ends the 
string. 
NOTE 
There are no provisions for overflow. 


RELATED FUNCTIONS: 


atof, atoi, scanf. 
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im 
| 


calloc 


calloc 
Heaps memory allocation. 
SYNTAX: 


char *calloc (nelem, elsize) 
unsigned nelem, elsize; 


ARGUMENTS : 
nelem 
Number of elements. 
elsize 
Size of each element in characters. 
DESCRIPTION: 


The calloc function allocates space for an array of 
elements. The space is initialized to zeros. 


RETURN VALUE: 

The calloc function returns a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any 
type of object. 

DIAGNOSTICS: 

If the heap does not contain enough memory and cannot be 
sufficiently expanded to meet the request, the variable errno 
is set to ENOMEM or ENOSPC and a null character pointer is 
returned. 

RELATED FUNCTIONS: 


free, malloc, realloc. 
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ceil 


Ceiling function. 
SYNTAX 3 


double ceil (x) 
Gouble x; 


ARGUMENTS: 
x 

Double-precision value to be compared. 
DESCRIPTION: 


The ceil function returns the smallest integer not less 
than x. 


RELATED FUNCTIONS: 


abs, fabs, floor, fmod. 
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clearerr 


clearerr 
File status inquiry -- clear error indicator. 
SYNTAX $ 
# include <stdio.h> 


clearerr (file) 
FILE *file; 


ARGUMENTS : 
file 

File pathname. 
DESCRIPTION: 


The clearerr function resets the error indication on the 
named file. 


The clearerr function is a macrocall; it cannot be 
redeclared. 


RELATED FUNCTIONS: 


feof, ferror, fileno, fopen, open. 
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clock 


clock 
Report CPU time used. 
SYNTAX: 
long clock ( ) 
ARGUMENTS : 
None. 
DESCRIPTION: 
Clock returns the amount of CPU time (in microseconds) used 


Since the first call to clock. The time reported is the sum 
of the user and system times of the calling process. 
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close 


close 
Closes a file. 
SYNTAX: 
# include <stdio.h> 


int close (fildes) 
int fildes; 


ARGUMENTS: 
fildes 

File descriptor obtained from a create or open function. 
DESCRIPTION: 
The close function closes and deletes a file. The close 
function closes the file descriptor indicated by fildes. A 
shared file is not removed until the last user executes a 
close. 
RETURN VALUE: 
Upon successful completion, a value of 0 is returned. 
Otherwise, a value of -l is returned. The variable errno is 
set to indicate the error. 


DIAGNOSTICS: 


The close function fails if fildes is not a valid, open file 
descriptor. 


RELATED FUNCTIONS: 


creat, open. 
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Cos 


Cosine function. 
SYNTAX: 
# include <math.h> 


double cos (x) 
double x; 


ARGUMENTS 3: 
x 

Double-precision value of the angle in radians. 
DESCRIPTION: 
The cos function returns the cosine of a radian argument. 
The caller should check the magnitude of the argument to 
ensure that the result is meaningful. 


RELATED FUNCTIONS: 


acos, aSin, atan, atan2, Sin, tan. 
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Hyperbolic function. 
SYNTAX: 
# include <math.h> 


double cosh (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value. 
DESCRIPTION: 


The cosh function computes the hyperbolic 
real arguments. 


DIAGNOSTICS: 


The cosh function returns a huge value of 
when the correct value would overflow. 


RELATED FUNCTIONS: 


Sinh, tanh. 
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creat 


creat 


Creates a new file or rewrites an existing one. 
SYNTAX 

int creat (path, mode) 

char *path; 

int mode; 
ARGUMENTS : 
path 

File pathname. 
mode 

File access--ignored (see below). 
DESCRIPTION: 
The creat function creates a new sequential file or prepares 
to rewrite an existing file named by the pathname pointed to 
by the path argument. 
The mode argument (which in a UNIX operating system sets file 
access) is ignored. Access Control List (ACL) rights for the 
file are determined by whatever ACLs currently apply to the 
file. 


If the file exists, the length is truncated to 0 and the mode 
and owner are unchanged. 


RETURN VALUE: 

Upon successful completion, the file descriptor (a non- 
negative integer) is returned and the file is opened for 
writing. The file descriptor is set to remain open across 
exec functions (see fcntl). The file pointer is set to the 
beginning of the file. No process can have more than 20 
files open simultaneously. 


Otherwise, a value of -1 is returned, and the variable errno 
1s set to indicate the error. 


RELATED FUNCTIONS: 


close, open, read, write. 
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ctime 
Converts date and time to ASCII. 
SYNTAX: 
| # include <time.h> 


char *ctime (clock) 
long *clock; 


ARGUMENTS : 
clock 


Long integer pointer to the time in seconds since | 
midnight GMT, Jan. 1, 1970 (such as returned by time). 


DESCRIPTION: 
The ctime function converts a time into ASCII and returns a 
pointer to a 26-character string in the following form (all 
fields have constant width): 

Sat Aug 10 10:24:54 1985\n\0 


The structure declaration from the include file is: 


struct tm { 


int tm_sec; 
int tm_min; 
int tm_hour; 
int tm_mday; 
int tm_mon; 
int tm_year; 
int tm_wday; 
int tm_yday; 
int tm_isdst; 


}; 


These quantities give the time on a 24-hour clock, day of 
month (1-31), month of year (0-11), day of week (Sunday - 0), 
year - 1900, day of year (0-365), and a flag that is nonzero 
if daylight savings time is in effect. 


The external long variable timezone contains the difference, 
in seconds, between GMT and local standard time (in EST, 
timezone is 5-60-60); the external variable daylight is 
and only if, the standard U.S. daylight savings 


Sion should be applied. 
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NOTE 


The return values point to static data whose 
contents are overwritten by each call. 


RELATED FUNCTIONS: . 


asctime, gmtime, localtime, time, tzset. 


ctime 
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drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, 
seed48, lcong48 


Generate uniformly distributed pseudorandom numbers. 
SYNTAX: 


double drand48 ( ) 
double erand48 xX;[3]; 


long lrand48 ( ) 


long nrand48 (Xj) 
unsigned short x; [3]; 


long mrand48 ( ) 


long jrand48 (Xj) 
unsigned short X;[3]; 


void srand48 (seedval) 
long seedval; 


unsigned short *seed48 (seedl6v) 
unsigned short seedl6v[3]; 


void lcong48 (param) 
unsigned short param[{7]; 


DESCRIPTION: 

This family of functions generates pseudorandom numbers using 
the well-known linear congruential algorithm and 48-bit 
integer arithmetic. 

Functions drand48 and erand48 return non-negative double- 
precision floating-point values uniformly distributed over 
the interval [0.0, 1.0). 


Functions lrand48 and nrand48 return non-negative Zong. 
integers uniformly distributed over the interval [0, 231). 


Functions mrand48 and jrand48 return signed_long_ integers 
uniformly distributed over the interval [-231, 231), 
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Functions srand48, seed48, and lcong48 are initialization 
entry points, one of which should be invoked before either 
drand48, lrand48, or mrand48 is called. (Although it is not 
recommeded practice, constant default initializer values will 
be supplied automatically if drand48, lrand48, or mrand48 is 
called without a prior call to an initialization entry 
point.) Functions erand48, nrand48, and jrand48 do not 
require an initialization entry point to be called first. 


All the routines work by generating a sequence of 48-bit 
integer values, Xj, according to the linear congruential 
formula: 


Xn+1 = (aXp + C)mod m n>=0 
The parameter m = 248; hence 48-bit integer arithmetic is 
performed. Unless lcong48 has been invoked, the multiplier 
value a and the addend value c are given by: 


a 
Cc 


5DEECE66D1¢6 = 2736731631558 
Big = 13g. 


The value returned by any of the functions drand48, erand48, 
lrand48, nrand48, mrand48, or jrand48 is computed by first 
generating the next 48-bit Xj in the sequence. Then the 
appropriate number of bits, according to the type of data 
item to be returned, are copied from the high-order 
(leftmost) bits of Xj; and transformed into the returned 
value. 


The functions drand48, lrand48, and mrand48 store the last 
48-bit Xj generated in an internal buffer; that is why they 
must be intialized prior to being invoked. The functions 
erand48, nrand48, and jrand48 require the calling program to 
provide storage for the successive Xj values in the array 
specified as an argument when the functions are invoked. 

That is why these routines do not have to be initialized; the 
calling program merely has to place the desired initial value 
of Xj; into the array and pass it as an argument. By using 
different arguments, functions erand48, nrand48, and jrand48 
allow separate modules of a large program to generate several 
independent streams of pseudorandom numbers, i.e., the 
sequence of numbers in each stream will not depend upon how 
many times the routines have been called to generate numbers 
for the other streams. 


The initializer function srand48 sets the high-order 32 bits 
of Xj to the 32 bits contained in its argument. The 
low-order 16 bits of Xj are set to the arbitrary value 
330E1¢. 
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The initializer function seed48 sets the value of Xj to the 
48-bit value specified in the argument array. In addition, 
the previous value of Xj is copied into a 48-bit internal 
buffer, used only by seed48, and a pointer to this buffer is 
the value returned by seed48. This returned pointer, which 
can just be ignored if not needed, is useful if a program is 
to be restarted from a given point at some future time. Use 
the pointer to get at and store the last Xj value, and then 
use this value to reinitialize via seed48 when the program is 
restarted. 


The initialization function lcong48 allows the user to 
specify the initial Xj, the multiplier value a, and the 
addend value c. Argument array elements param[0-2] specify 
Xi, param[3-5] specify the multiplier a, and param[6] 
specifies the 16-bit addend c. After lcong48 has been 
called, a subsequent call to either srand48 or seed48 
restores the "standard" multiplier and addend values, a and 
c, specified on the previous page. 
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ecvt 


Output conversion. 
SYNTAX: 
char *ecvt (value, ndigit, decpt, sign) 
double value; 
int ndigit, *decpt, *sign; 
ARGUMENTS : 
value 
Double-precision value to be converted. 
ndigit 
Number of digits in output string. 
decpt 
Pointer to position of the decimal point relative to the 
beginning of the string (negative means to the left of 
the returned digits). 
Sign 


If the sign of the result is negative, the word pointed 
to by sign is nonzero; otherwise it is zero. 


DESCRIPTION: 
The ecvt function converts a value to a null-terminated 
string of ndigit digits and returns a pointer thereto. If 
the sign of the result is negative, the word pointed to by 
Sign is nonzero; otherwise it is zero. The low-order digit 
is rounded. 

NOTE 


The return values point to static data whose con- 
tents are overwritten by each call. / 


RELATED FUNCTIONS: 


fcevt, gcvt, printf. 
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errno 
System error message number. 
SYNTAX: 
extern int errno; 
ARGUMENTS : 
None. 
DESCRIPTION: 


The external variable errno is set when errors occur but not 
cleared when nonerroneous calls are made. 
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execl 
Execute a bound unit. 
SYNTAX: 


int execl(path,argg,arg),...,argn, (unsigned char *) 0) 
unsigned char *path, *argo, *arg,, ..., *argn; 


ARGUMENTS : 
path 


Pointer to a pathname that identifies the new process 
bound unit. 


argg, arg], .++, argn 


Pointers to null-terminated strings. These strings 
constitute the argument list available to the new 
process. By convention, at least argo must be present 
and point to a string that is the same as path (or its 
file-name component). 


DESCRIPTION: 

The execl function transforms the calling process into a new 
process. The new process is constructed from an ordinary 
bound unit called the new process bound unit. 


A pointer to the environment of the calling process is placed 
in the global cell: 


extern unsigned char **environ; 


It is used to pass the environment of the calling process to 
the new process. 


The execl function fails and returns to the calling process 
if: 


@ One or more components of the pathname do not exist 
[ENOENT ]. 


e A directory-name component of path is not a directory 
([ENOTDIR]. 


@e List access is denied for a directory named in path 
[EACCES]. 
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e The new process bound unit is not a bound unit, or the 
calling process lacks execute access to it [EACCES]. 


e The path, argv, or envp argument points to an invalid 
address [EFAULT]. 


RETURN VALUE: 

If execi returns to the calling process, an error has 
occurred; the return value is -1, and the variable errno is 
set to indicate the error. 


RELATED FUNCTIONS: 


execle, execv, execve, exit, getenv. 
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execle 
Execute a bound unit. . 
SYNTAX 3 


int execle(path,argg,arg),...,argyn, (unsigned char 
*)0),envp)unsigned char *path, *argg, *arg), ..-, *argn, 
xenvp []; 


ARGUMENTS : 
path 


Pointer to a pathname that identifies the new process 
bound unit. 


argg, arg), .--, argn 


Pointers to null-terminated strings. These strings 
constitute the argument list available to the new 
process. By convention, at least argo must be present 
and point to a string that is the same as path (or its 
file name component). 


envp 


Array of character pointers to null-terminated strings. 
These strings constitute the environment for the new 
process. The array is terminated by a null character 
pointer. 


DESCRIPTION: 


The execle function transforms the calling process into a new 
process. The new process is constructed from an ordinary 
bound unit called the new process bound unit. 


The new process also inherits the following attributes from 
the calling process: 


Process ID 

Parent process ID 

Process group ID 

TTY group ID 

Time left until an alarm signal 
Current working directory 

Root directory 

File mode creation mask 

File size limit. 
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The execle function fails and returns to the calling process 
if: 


@e One or more components of the pathname do not exist 
[ENOENT]. 


e A directory-name component of path is not a directory 
[ENOTDIR]. 


e List access is denied for a directory named in path 
[EACCES]. 


@e The new process bound unit is not a bound unit, or the 
calling process lacks execute access to it [EACCES]. 


e The path, argv, or envp argument points to an invalid 
address [EFAULT]. 


RETURN VALUE: 

If execle returns to the calling process, an error has 
occurred; the return value is -l, and the variable errno is 
set to indicate the error. 


RELATED FUNCTIONS: 


execl, execv, execve, exit. 
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execlip 
Execute a bound unit. 
SYNTAX: 


int execlp(file,argp,arg),...,arg,(unsigned char *)0) 
unsigned char *file, *arqg, *arq,, ..., *ardn; 


ARGUMENTS : 

file 
Pointer to the filename of the new process bound unit. 

argo, arg), «++, argn 
Pointers to null-terminated character strings. These 
strings constitute the argument list available to the new 
process. By convention, at least argg must be present 
and point to a string that is the same as path (or its 
filename component). 


DESCRIPTION: 


The execlp function transforms the calling process into a new 
process. The new process is constructed from an ordinary 


Car we Uwe Oe we ee 


bound unit called the new process bound unit. 

The directory containing the new process bound unit is found 
by searching the directories passed as the environment line 
"PATH= ... ". . 


A pointer to the environment of the calling process is placed 
in the global cell: 


extern unsigned char **environ; 


It is used to pass the environment of the calling process to 
the new process. 
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new process also inherits the following attributes from 
calling process: 


Process ID 

Parent process ID 

Process group ID 

TTY group ID 

Time left until an alarm signal 
Current working directory 

Root directory 

File mode creation mask 

File size limit. 


execlp function fails and returns to the calling process 


One or more components of a directory named in the 
environment line "PATH= ... " does not exist [ENOENT]. 


A directory-path component of "PATH= ... " iS not a 
directory [ENOTDIR]. 


List access is denied for a directory named in 
"PATH= ... " [EACCES]. 


The new process bound unit is not a bound unit, or the 
calling process lacks execute access to it [EACCES]. 


The argv argument points to an invalid address 
[EFAULT]. 


RETURN VALUE: 


If execlp returns to the calling process, an error has 
occurred: the return value is -l, and the variable errno is 
set to indicate the error. 


RELATED FUNCTIONS: 


execvp. 
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execv 
Execute a bound unit. 
SYNTAX: 


int execv (path, argv) 
unsigned char *path, *araqv []; 


ARGUMENTS : 
path 


Pointer to a pathname that identifies the new process 
bound unit. 


argv 


Array of character pointers to null-terminated strings. 
These strings constitute the argument list available to 
the new process. By convention, argv must have at least 
one member, and it must point to a string that is the 
same as path (or its file name component). The array is 
terminated by a null character pointer. 


DESCRIPTION: 

The execv function transforms the calling process into a new 
process. The new process is constructed from an ordinary 
bound unit called the new process bound unit. 


A pointer to the environment of the calling process is placed 
in the global cell: 


extern unsigned char **environ; 


It is used to pass the environment of the calling process to 
the new process. 
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The new process also inherits the following attributes from 
the calling process: 


Process ID 

Parent process ID 

Process group ID 

TTY group ID 

Time left until an alarm signal 
Current working directory 

Root directory 

File mode creation mask 

File size limit. 


The execv function fails and returns to the calling process 
if: 


@e One or more components of the pathname do not exist 
[ENOENT ]. 


e A directory-name component of path is not a directory 
[ENOTDIR]. 


e List access is denied for a directory named in path 
[EACCES ]. 


@e The new process bound unit is not a bound unit, or the 
calling process lacks execute access to it [EACCES]. 


e The path, argv, or envp argument points to an invalid 
address [EFAULT]. 


RETURN VALUE: 

If execv returns to the calling process, an error has 
occurred; the return value is -l, and the variable errno is 
set to indicate the error. 


RELATED FUNCTIONS: 


execl, execle, execve, exit. 
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execv 
Execute a bound unit. 
SYNTAX: 


int execve (path, argv, envp 
unsigned char *path, *argv I 


ARGUMENTS : 
path 


Pointer to a pathname that identifies the new process 
bound unit. 


argv 


Array of character pointers to null-terminated strings. 
These strings constitute the argument list available to 
the new process. By convention, argv must have at least 
one member, and it must point to a string that is the 
same as path (or its file name component). The array is 
terminated by a null character pointer. 


envp 
Array of character pointers to null-terminated strings. 
These strings constitute the environment for the new 
process. The array is terminated by a null character 
pointer. 

DESCRIPTION: 

The execve function transforms the calling process into a new 

process. The new process is constructed from an ordinary 

bound unit called the new process bound unit. 


A pointer to the environment of the cabins process is placed 
in the global cell: 


extern unsigned char **environ; 


It is used to pass the environment of the calling process to. 
the new process. 
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new process also inherits the following attributes from 
calling process: 


Process ID 

Parent process ID 

Process group ID 

TTY group ID 

Time left until an alarm signal 
Current working directory 

Root directory 

File mode creation mask 

File size limit. 


execv function fails and returns to the calling process 


One or more components of the pathname do not exist 
[ENOENT]. 


A directory-name component of path is not a directory 
[ENOTDIR]. 


List access is denied for a directory named in path 
[EACCES]. 


The new process bound unit is not a bound unit, or the 
calling process lacks execute access to it [EACCES]. 


The path, argv, or envp argument points to an invalid 
address [EFAULT]. 


RETURN VALUE: 


If execve returns to the calling process, an error has 
occurred; the return value is -l, and the variable errno is 
set to indicate the error. 


RELATED FUNCTIONS: 


execl, execle, execv, exit. 
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execv 
Execute a bound unit. 
SYNTAX: 


int execvp (file, argv) 
unsigned char *file, *argv [] 


ARGUMENTS : 
file 
Pointer to the filename of the new process bound unit. 
argv 
Array of character pointers to null-terminated strings. 
These strings constitute the argument list available to 
the new process. By convention, argv must have at least 
one member, and it must point to a string that is the 
same as path (or its file name component). The array is 
terminated by a null character pointer. 
DESCRIPTION: 
The execlp function transforms the calling process into a new 
process. The new process is constructed from an ordinary 
bound unit called the new process bound unit. 
The directory containing the new process bound unit is found 
by searching the directories passed as the environment line 
"PATH= ‘6 ies: “"<¢ 


A pointer to the environment of the calling process is placed 
in the global cell: 


extern unsigned char **environ; 


It is used to pass the environment of the calling process to 
the new process. 
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new process also inherits the following attributes from 
calling process: 


Process ID 

Parent process ID 

Process group ID 

TTY group ID 

Time left until an alarm signal 
Current working directory 

Root directory 

File mode creation mask 

File size limit. 


execvp function fails and returns to the calling process 


One or more components of a directory named in the 
environment line "PATH= ... " does not exist [ENOENT]. 


A directory-path component of "PATH= ... " is not a 
directory [ENOTDIR]. 


List access is denied for a directory named in 
"PATH= ... " [EACCES]. 


The new process bound unit is not a bound unit, or the 
calling process lacks execute access to it [EACCES]. 


The argv argument points to an invalid address 
[EFAULT]. 


RETURN VALUE: 


If execvp returns to the calling process, an error has 
occurred; the return value is -1, and the variable errno is 
set to indicate the error. 


RELATED FUNCTIONS: 


execlp. 
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exit 


Terminate a process. 
SYNTAX 


exit (status) 
int status; 


ARGUMENTS : 
status 

Status of operation. 
DESCRIPTION: 


The exit function terminates the calling process with the 
following consequences: 


@e All of the file descriptors open in the child 
(calling) process are closed. 


RELATED FUNCTIONS: 


Signal, wait. 
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exp 
Exponential function. 
SYNTAX: 
# include <math.h> 


double exp (x) 
double x; 


ARGUMENTS : 
x 
Double-precision value to be operated on. 
DESCRIPTION: 
The exp function returns e%, 
DIAGNOSTICS: 
The exp function returns a huge value when the correct value 
would overflow. A very large argument can also result in 
errno being set to ERANGE. 
RELATED FUNCTIONS: 


hypot, iog, pow, Sinh, sqrt. 


4-64 HHO7-01 


fabs 


fabs 
Absolute value function. 
SYNTAX: 


double fabs (x) 
Goubie x; 


ARGUMENTS : 
x 

Double-precision value to be operated on. 
DESCRIPTION: 


The fabs function returns |x| (that is, the absolute value 
of x). 


RELATED FUNCTIONS: 


abs, ceil, floor, fmod. 
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fclose 
Close a file. 
SYNTAX: 
# include <stdio.h> 


int fclose (file) 
FILE *file; 


ARGUMENTS: 
file 

File pathname. 
DESCRIPTION: 
The fclose function causes any buffers for the named file to 
be written to that file, and the file to be closed. Buffers 
allocated by the standard input/output system are freed. 


The fclose function is performed automatically upon calling 
exit. 


RETURN VALUE: 


This function returns 0 for success, and EOF if any errors 
were detected. 


RELATED FUNCTIONS: 


close, fflush, fopen, setbuf. 
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fentl 
File control. 
SYNTAX 3 
# inciude <fcnti.h> 


int fcntl (fildes, cmd, arg) 
int fildes, cmd, arg; 


ARGUMENTS: 
fildes 


Open file descriptor obtained from a creat, open, or 
fentl function. 


cmd 
Command (see below). 
arg 
Argument to cmd. 
DESCRIPTION: 
The fcntl function provides for control over open files. 
Acceptable values for cmd are as follows: 


F_DUPFD Duplicate the lowest-numbered available file 
descriptor greater than or equal to arg. The 
file descriptor shares the same open file(s), 
file pointer, and access mode. The file 
Status flags have the values of the original 
flags. The close-on-exec flag associated 
with the new file descriptor is set. 


F_GETFD Get the close-on-exec flag associated with 
the file descriptor fildes. If the low-order 
bit is zero, the file remains open across 
exec functions; otherwise, the file is closed 
on execution of exec. 


F_SETFD Set the close-on-exec flag associated with 


the file descriptor fildes to the low-order 
bit or arg. 
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F_GETFL Get the status flags of file. 
F_SETFL Set the status flags of file to arg. 
RETURN VALUE: 


Upon successful completion, the value returned depends on the 
cmd argument, as follows: 


F_DUPFD -- A new file descriptor 

F_GETFD -- Value of flag (only low-order bit defined) 
F_SETFD -- Value other than -1l 

F_GETFL -- Value of file flags 

F_SETFL -- Value other than -l. 


Otherwise, a value of -1 is returned and the variable errno 
is set to indicate the error. 


DIAGNOSTICS: 
The fcntl function fails it: 


e The fildes argument does not point to a valid, open 
file descriptor [EBADF]. 


e The cmd argument is F_DUPFD and twenty file 
descriptors are currently open [EMFILE]. 


e The cmd argument is F_DUPFO and the arg argument is 
negative or greater than twenty [EINVAL] or the cmd 
argument is F_SETFL and the arg argument is invalid. 

RELATED FUNCTIONS: 


close, exec, open. 
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Output conversion. 
SYNTAX: 
char *fcvt (value, ndigit, decpt, sign) 
Goubie value; 
int ndigit, *decpt, *sign; 
ARGUMENTS : 
value 
Double~precision value to be converted. 
ndigit 
Number of digits to be returned. 
decpt 
Pointer to position of the decimal point relative to the 
beginning of the string (negative means to the left of 
the returned digits). 
sign 


If the sign of the result is negative, the word pointed 
to by sign is nonzero; zero otherwise. 


DESCRIPTION: 
The ecvt function converts a value to a null-terminated 
string of ndigit digits and returns a pointer thereto. The 
correct digit has been rounded for FORTRAN F-format output of 
the number of digits specified by the ndigit argument. 

NOTE 


The return values point to static data whose con- 
tents are overwritten by each call. 


RELATED FUNCTIONS: 


ecvt, gcvt, printf. 
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fdopen 
Open a file. 
SYNTAX: 
# include <stdio.h> 
FILE *fdopen (fildes, type) 
int fildes; 
char *type; 
ARGUMENTS : 
fildes 
Number of a file descriptor. 
type 
Access type (see below). 
DESCRIPTION: 
The fdopen function opens a file descriptor obtained from the 
open, dup, or creat function. The read/write indicator is 


set according to the type argument. 


When a file is opened for update, both input and output are 
allowed. 


The type argument consists of all valid combinations of r, vw, 
a, +, and b. The argument has these meanings: 


r -- Open text file for reading only 

w -- Create text file for writing 

a -- Append to text file 

r+ -- Update (read/write) text file 

wt -- Create text file for update (read/write) 


a+ -- Append (read/write) at end of text file. 
RELATED FUNCTIONS: 


fclose, fopen, freopen, open. 
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File status inquiry -- check for end of file. 
SYNTAX: 
# include <stdio.h> 


int feof (file) 
FILE *file; 


ARGUMENTS : 
file 

File pathname. 
DESCRIPTION: | 


The feof function returns nonzero when EOF is read on the 
named input file; otherwise, it returns zero. 


The feof function is a macrocall; it cannot be redeclared. 
RELATED FUNCTIONS: 


Clearerr, ferror, fileno, fopen, open. 
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ferror 
File status inquiry -- check for I/O error. 
SYNTAX: 
# include <stdio.h> 


int ferror (file) 
FILE *file 


ARGUMENTS: 
file 

File pathname. 
DESCRIPTION: 
The ferror function returns a nonzero value when an error has 
occurred while reading or writing the named file; otherwise, 
it returns zero. Unless cleared by the clearerr function, 
the error indication remains until the file is closed. 
The ferror function is a macrocall; it cannot be redeclared. 


RELATED FUNCTIONS: : 


clearerr, feof, fileno, fopen, open. 
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fflush 
Flush a file. 
SYNTAX: 
# include <stdio.h> 


int fflush (file) 
FILE *file; 


ARGUMENTS : 
file 

File pathname. 
DESCRIPTION: © 


‘The fflush function causes any buffered data for the named 
output file to be written to that file. 


RETURN VALUE: 


This function returns 0 for success, and EOF if any errors 
were detected. 


RELATED FUNCTIONS: 


close, fclose, fopen, setbuf. 
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fgetc 


Get character from file. 
SYNTAX: 
# include <stdio.h> 


int fgetc (file) 
FILE *file; 


ARGUMENTS : 
file 

File pathname. 
DESCRIPTION: 
The fgetc function returns the next character from the named 
input file. The fgetc function behaves like getc, but is a 
genuine function, not a macrocall; it can therefore be used 
as an argument. The fgetc macrocall runs more slowly than 
getc, but takes less space per invocation. 


DIAGNOSTICS: 


This function returns the value -l at end of file. 


ferror, fopen, fread, getc, getchar, gets, getw, putc, 
scanf. 
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fgets 

Gets characters from a file. 

SYNTAX: 
# include <stdio.h> 
char *fgets (s, n, file) 
char *s; 
int n; 
FILE *file; 

ARGUMENTS : 


Ss 


Pointer to string of characters returned, including a. 
newline character. . 


Number of characters to get -1l. 
file 

File pathname. 
DESCRIPTION: 
The fgets function reads n-l characters, or up to a newline 
character (which is retained), whichever comes first, from 
the file into the string s. The last character read into s 
is followed by a null character. 
RETURN VALUE: 
The fgets function returns its first argument. 


DIAGNOSTICS: 


The fgets function returns the constant pointer NULL upon the 
end of file or on an error. 


NOTE 


The fgets function retains in string s a newline 
character that ends input. 


RELATED FUNCTIONS: 
ferror, fopen, fread, getc, gets, puts, scan. 


4-75 HHO7-01 


fileno 


fileno 
File status inquiry -- get file descriptor. 
SYNTAX: 
# include <stdio.h> 


fileno (file) 
FILE *file; 


ARGUMENTS : 
file 

File pathname. 
DESCRIPTION: 


The fileno function returns the integer file descriptor 
associated with the file (see open). 


The fileno function is a macrocall; it cannot be redeclared. 
RELATED FUNCTIONS: 


clearerr, feof, ferror, fopen, open. 
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floor 
Floor function. 
SYNTAX: 


doubie fioor (x) 
Gouble x; 


ARGUMENTS : 
x 

Double-precision value for comparison. 
DESCRIPTION: 


The floor function returns the largest integer (as a double- 
precision number) not greater than x. 


RELATED FUNCTIONS: 


abs, ceil, fabs, fmod. 
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fmod 
Remainder function. 
SYNTAX: 


double fmod (x, y) 
double x, y; 


ARGUMENTS: 
x 


Double-precision value. — 


Double-precision value. 
DESCRIPTION: 
The fmod function returns x if y is 0; otherwise, it returns 
the number f with the same sign as x such that x = i*y + f, 
for some integer i, and0 <f < y. 


RELATED FUNCTIONS: 


abs, ceil, fabs, floor. 
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fopen 
Open a file. 
SYNTAX 
# include <stdio.h> 


FILE *fopen (filename, type) 
char *filename, *type; 


ARGUMENTS : 
filename 
File pathname. 
type 
Access type (see below). 
DESCRIPTION: | | 


The fopen function opens the file named by filename and 
associates a file with it. 

The fopen function returns a file pointer that identifies the 
file in subsequent operations. 


When a file is opened for update, both input and output are 
allowed. 


The type argument consists of all valid combinations of r, vw, 
a, and +. The argument has these meanings: 


r .-- Open text file for reading only 

w -- Create text file for writing 

a -- Append to text file 

r+ —- Update (read/write) text file 

w+ -- Create text file for update (read/write) 


a+ -- Append (read/write) at end of text file. 
DIAGNOSTICS: 


The fopen function returns a null pointer if the file cannot 
be accessed. 


RELATED FUNCTIONS: 


fclose, fdopen, freopen, open. 
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fprintf 
Formats output to file. 
SYNTAX: 
# include <stdio.h> 


int fprintf (file, format [, arg] ... ) 
FILE *file; 
char *format; 


ARGUMENTS : 
file 

Pathname of file to receive output. 
format 

Format string (see below). 
arg 

Optional argument to be printed. 
DESCRIPTION: 


The fprintf function places output on the named output file. 
This function converts, formats, and prints its arguments 
under control of the format. The format is a character 
string that contains two types of objects: plain characters, 
which are simply copied to the output file, and conversion 
specifications, each of which results in the fetching of zero 
Or more arguments. The results are undefined if there are 
insufficient arguments for the format. If the format is 
exhausted while arguments remain, the excess arguments are 
Simply ignored. 


Each conversion specification is introduced by the percent 
(%) character. After the percent character, the following 
appear in sequence; 


@ Zero or more flags, which modify the meaning of the 
conversion specification. 


@e An optional decimal digit string specifying a minimum 
field width. If the converted value has fewer char- 
acters than the field width, it is blank-padded on the 
left (or right, if the left-adjustment flag has been 
given) to make up the field width. 
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e A precision that gives the minimum number of digits to 
appear for the d, o, u, x, or X conversions, the 
number of digits to appear after the decimal poirt for 
the e and f conversions, the maximum number of 
significant digits for the g conversion, the maximum 
number of characters to be printed from a string ins 
conversion, or the minimum number of digits to appear 
in the word address portion of a converted pointer for 
the p or P conversions. The precision takes the form 
of a period (.) followed by a decimal digit string; a 
null digit string is treated as zero. 


@ An optional 1 specifying that a following d, o, u, x, 
or X conversion character applies to a long integer 
argument. 


e A character that indicates the type of conversion to 
be applied. 


A field width or precision can be indicated by an asterisk 
(*) instead of a digit string. In this case, an integer 
argument supplies the field width or precision. The argument 
that is actually converted is not fetched until the conver- 
sion letter is seen, so the arguments specifying field width 
or precision must appear before the argument (if any) to be 
converted. 


The flag characters and their meanings are: 


= 2 The result of the conversion is left-justified 
within the field. 


+ The result of a Signed conversion always 
begins with a sign (+ or -). 


blank If the first character of a signed conversion 
is not a sign, a blank precedes the result. 
This implies that if the blank and + flags 
both appear, the blank flag is ignored. The p 
and P conversions ignore this flag. 
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The conversion 


d,o,u,x,X 


The value is to be converted to an "alternate 
form." For c, d, s, and u conversions, the 
flag has no effect. For o conversions, it 
increases the precision to force the first 
digit of the result to be a zero. For x (X) 
conversion, a nonzero result will have 0x (0X) 
preceding it. For e, E, f, g, and G conver- 
sions, the result always contains a decimal 
point, even if no digits follow the point 
(normally, a decimal point appears in the 
result of these conversions only if a digit 
follows it). For g and G conversions, trail- 
ing zeros are not removed from the result (as 
they normally are). For p or P conversions, 
the word-address and character-address por- 
tions of the converted pointer will each be 
preceded by 0x or 0X, except when the 
portion's value is zero. 


characters and their meanings are: 


The integer argument is converted to signed 
decimal, unsigned octal, unsigned decimal, or 
unsigned hexadecimal notation (x and X), 
respectively; the letters abcdef are used for 
x conversion and the letters ABCDEF for X 
conversion, The precision specifies the 
minimum number of digits to appear; if the 
value being converted can be represented in 
fewer digits, it iS expanded with leading 
zeros. The default precision is 1. The 
result of converting a 0 value with a 
precision of 0 is a null string (unless the 
conversion is o, x, or X and the # flag is 
present). 


The float or double argument is converted to 
decimal notation in the style "[{-]Jddd.ddd", 
where the number of digits after the decimal 
point is equal to the precision specification. 
If the precision is missing, six digits are 
output; if the precision is explicitly 0, no 
decimal point appears. 
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e,E The float or double argument is converted in 
the style "[-]d.ddde+dd", where there is one 
digit before the decimal point and the number 
of digits after it is equal to the precision; 
when the precision is missing, six digits are 
produced; if the precision is 0, no decimal 

' point appears. The E format code produces a 
number with E instead of e introducing the 
exponent. The exponent always contains 
exactly two digits. 


g, G The float or double argument is printed in 
style e (or in style E in the case of aG 
format code), with the precision specifying 
the number of significant digits. The style 
used depends on the value converted; style e 
is used only if the exponent resulting from 
the conversion is less than -4 or greater than 
the precision. Trailing zeros are removed 
from the result; a decimal point appears only 
if it is followed by a digit. 


Cc The character argument is printed. 


s The argument is taken to be a string 
(character pointer) and characters from the 
string are printed until a null character (\0) 
is encountered or the number of characters 
indicated by the precision specification is 
reached. If the precision is missing, it is 
taken to be infinite, so all characters up to 
the first null character are printed. 


% Print a %; no argument is converted. 
In no case does a nonexistent or small field width cause 
truncation of a field; if. the result of a conversion is wider 
than the field width, the field is simply expanded to contain 
the conversion result. Characters generated by fprintf are 
printed as if putchar had been called. 
RETURN VALUE: 
This function returns the number of characters transmitted. 
' DIAGNOSTICS: 
If this function encounters an invalid string pointer, it 
behaves as if it has encountered a valid pointer to a null 


String. An error condition is indicated to the calling 
function by a negative return value. 
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EXAMPLES: 


To print a date and time in the form "Sunday, July 3, 10:02", 
where weekday and month are pointers to null-terminated 
strings: 
fprintf(temp,"%s, %s %d, %.2d:%.2d",weekday,month,day,hour,min); 
To print pi to five decimal places: 
fprintf(output,"pi = %.5f£", 4*atan(1.0)); 
RELATED FUNCTIONS: 


ecvt, printf, putc, scanf, sprintf. 
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fputc 


Puts a character ona file. 
SYNTAX: 
# include <stdio.h> 


fputc (c, file) 
FILE *file; 


ARGUMENTS : 
c 

Character to write to file. 
file 

File pathname. 
DESCRIPTION: 
The fpute function appends the character c to the named 
output file. Unlike putc, it is a genuine function rather 
than a macrocall; it can therefore be used as an argument. 
The fputc function runs more slowly than putc, but takes less 
space per invocation. | 
RETURN VALUE: 
The fputc function returns the character written. 
DIAGNOSTICS: 
The fputc function returns the constant EOF when it 
encounters an error. Since this is a good integer, ferror 
should be used to detect putw errors. 


RELATED FUNCTIONS: 


ferror, fopen, fwrite, getc, printf, putc, putchar, puts, 
putw. 
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fputs 
Puts a string on a file. 
SYNTAX: 
# include <stdio.h> 
int fputs (s, file) 
char *s; 
FILE *file; 
ARGUMENTS: 
s 
String to be written to the file. 
file 
File pathname. 


DESCRIPTION: 


The fputs function copies the null-terminated string s to the 
named output file. 


This function does not copy the terminating null character. 
DIAGNOSTICS: 
This function returns EOF if it encounters an error. 

NOTE 


The fputs function does not append a newline 
character. 


RELATED FUNCTIONS: 


ferror, fopen, fwrite, gets, printf, putc, puts. 
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fread 
Buffered input. 
SYNTAX: 
# inciude <stdio.h> 
fread (buf_ptr, size, nitems, file) 
int size; 
int nitems; 
char *buf_ptr; 
FILE *file; 
ARGUMENTS: 
buf_ptr 
Buffer address poten: 
size 
Item size in characters. 
nitems 
Number of eens to read. 
file | 
File pathname. 


DESCRIPTION: 


The fread function reads, into an array beginning at buf _ptr, 
nitems of size characters each from the named input file. 


RETURN VALUE: 
The fread function returns the number of items actually read. 
RELATED FUNCTIONS: 


fopen, fwrite, getc, gets, printf, putc, puts, read, 
scanf, write. 
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Frees heap memory. 
SYNTAX: 


void free (ptr) 
char *ptr; 


ARGUMENTS ; 


ptr 


Pointer to a block previously allocated by calloc or 


malloc; this space is made available for further 
allocation. 


DESCRIPTION: 


The malloc and free functions together provide a simple, 


general-purpose memory allocation package. 


DIAGNOSTICS: 


Unspecified results occur if free acts on some random number. 


RELATED FUNCTIONS: 


calloc, malloc, realloc. 
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freopen 


Reopens a file. 
SYNTAX: 
# include <stdio.h> 
FILE *freopen (filename, type, auie) 
char *filename, *type; 
FILE *file; 
ARGUMENTS : 
filename 
New file pathname. 
type 
Access type (see below). 
file 
Old file pathname. 
DESCRIPTION: 
The freopen function substitutes the named file in place of 
the open file. It returns the original value of file. The 
_ original file is closed, regardless of whether the open 


ultimately succeeds. 


The freopen function is used to attach the pre-opened 
constant names stdin, stdout, and stderr to specified files. 


When a file is opened for update, both input and output are 
allowed. 


The type argument consists of all valid combinations of r, w, 
a, and +. The argument has these meanings: 


r -- Open text file for reading only 

w -- Create text file for writing 

a -- Append to text file 

r+ -- Update (read/write) text file 

w+ -- Create text file for update (read/write) 


a+ -- Append (read/write) at end of text file. 
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DIAGNOSTICS: 


The freopen function returns a null pointer if filename 
cannot be accessed. 


RELATED FUNCTIONS: 


fclose, fdopen, fopen, open. 
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frexp 
Splits into mantissa and exponent. 
SYNTAX 3 
double frexp (value, eptr) 
Gouble value; 
int *eptr; 
ARGUMENTS : 
value 
Double-precision value to be processed. 
eptr 
Pointer to exponent. 
DESCRIPTION: 
The frexp function returns the mantissa, x, of the 
Gouble-precision value as a double-precision quantity. The 
magnitude of x is less than 1 and greater than 1/16. It 
stores the exponent at the location pointed to by eptr. The 
exponent is the integer n such that vaiue = x*2", 


RELATED FUNCTIONS: 


ldexp, modf. 
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Escanf 
Formatted input conversion. 
SYNTAX: 
# include <stdio.h> 
fscanf (file, format [, pointer]...) 
FILE *file; 
char *format; 
ARGUMENTS ;: 
file 
Input file pathname. 
format 
Control string format (see below). 
pointer 


Set of arguments indicating where the converted input 
should be stored. 


DESCRIPTION: 


The fscanf function reads from the named input file. This 
function reads characters, interprets them according to a 
format, and stores the results in its arguments. It requires 
a control string format described below, and an optional set 
of pointer arguments indicating where the converted input 
should be stored. | 


The control string usually contains conversion 
specifications, which are used to direct interpretation of 
input sequences. The control string may contain: 


1. Blanks, tabs, or newline characters, which cause 
input to be read up to the next non-white-space 
character. 


2. An ordinary character (not %), which must match the 
next character of the input file. 


3. Conversion specifications, consisting of the 
character %, an optional assignment suppressing 
character *, an optional numerical maximum field 
width, and a conversion character. 
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A conversion specification directs the conversion of the next 
input field; the result is placed in the variable pointed to 
by the corresponding argument, unless assignment suppression 
was indicated by *. An input field is defined as a string of 
nonspace characters; it extends to the next inappropriate 
character or until the field width, if specified, is 
exhausted. 


The conversion character indicates the interpretation of the 
input field; the corresponding pointer argument must usually 
be of a restricted type. The following conversion characters 
are valid: 


% A single % is expected in the input at this point; 
no aSSignment is done. 


d A decimal integer is expected; the corresponding 
argument should be an integer pointer. 


fe) An octal integer is expected; the corresponding 
argument should be an integer pointer. 


x A hexadecimal integer is expected; the corresponding 
argument should be an integer pointer. 


s A character string is expected; the corresponding 
argument should be a character pointer pointing to 
an array of characters large enough to accept the 
string and a terminating \0, which is added 
automatically. The input field is terminated by a 


space or newline character. 


Cc A character is expected; the corresponding argument 
should be a character pointer. The normal skip over 
space characters is suppressed in this case; to read 
the next nonspace character, use %ls. If a field 
width is given, the corresponding argument should 
refer to a character array; the indicated number of — 
characters is read. 


e,f£ A floating-point number is expected; the next field 
is converted accordingly and stored through the 
corresponding argument, which should be a pointer to 
a fioat. The input format for fioating-point 
numbers iS an optionally signed string of digits, 
possibly containing a decimal point, followed by an 
optional exponent field consisting of an E or ane, 
followed by an optionally signed integer. 
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[ Indicates a string that is not to be delimited by 
space characters. The left bracket is followed by a 
set of characters and a right bracket; the charac- 
ters between the brackets define a set of characters 
making up the string. If the first character is not 
a circumflex (*), the input field consists of all 
characters up to the first character that is not in 
the set between the brackets; if the first character 
after the left bracket is a circumflex, the input 
field consists of all characters up to the first 
character that is in the set of the remaining 
characters between the brackets. The corresponding 
argument must point to a character array. 


The conversion characters d, o, and x can be capitalized 
and/or preceded by 1 to indicate that a pointer to long 
rather than to int is in the argument list. Similarly, the 
conversion characters e and f may be capitalized and/or 
preceded by 1 to indicate that a pointer to double rather 
than to float is in the argument list. 


The fscanf conversion terminates at EOF, at the end of the 
control string, or when an input character conflicts with the 
control string. In the latter case, the offending character 
is left unread in the input file. 


RETURN VALUE: 
The fscanf function returns the number of successfully 
matched and assigned input items: this number can be zero in 
the event of an early conflict between an input character and 
the control string. If the input ends before the first 
conflict or conversion, EOF is returned. 

NOTE 


Trailing white space (including a newline character) 
is left unread unless matched in the control string. 


DIAGNOSTICS: 


This function returns EOF at the end of input and a short 
count for missing or illegal data items. 


NOTE 


The success of literal matches and suppressed assign- 
ments is not directly determinable. 
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EXAMPLES: 
The calls 


int i; float x; char name[50]; 
fscanf (names, "%d%f%s", &i, &x, Name); 


with the input line: 
25 54.32E-1 brenda 


assigns to i the value 25, to x the value 5.432, and name 
contains brenda\0. Or: 


int i; float x; char name[50]; 
fscanf (data, "%2d%£%*d%[1234567890]", &i, &x, name); 


with input: 
56789 0123 56a72 


assigns 56 to i, 789.0 to x, skip 0123, and places the string 
56\0 in name. The next call to getchar returns a. 


RELATED FUNCTIONS: 


4-95 HH07-01 


fstat 


fstat 


Get file status. 
SYNTAX: 


# include <types.h> 
# include <stat.h> 


int fstat (fildes, buf) 
int fildes; 
Struct stat *buf; 
ARGUMENTS: 
fildes 
File descriptor of the open file. 


buf 


Pointer to a static structure into which information is 
placed concerning the file. 


DESCRIPTION: 

The fstat function obtains information about an open file 
known by the file descriptor fildes, obtained from a 
successful open, creat, or dup function. 


The contents of the structure pointed to by buf include the 
following members: 


ushort st_mode; /*File mode 
ino_t st_ino; /*Inode number (N/A in MOD 400) 
dev_t st_dev; /*ID of device containing 

/*a directory entry for this file 
dev_t st_rdev; /*ID of device 


/*This entry is defined only for 
/*character special or block speci 


files 
short st_nlink; /*Number of links (N/A in MOD 400) 
ushort st_uid; /*User ID of the file's owner 
ushort St_gid; /*Group ID of the file's group 
off t st_size;  /*File size in characters (N/A) 
time_t St_atime; /*Time of last access 
time_t St_mtime; /*Time of last data modification 


/*Times measured in seconds since 
00:00:00 GMT, Jan. 1, 1970 
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The st_atime member is the date/time when the file was iast 
accessed. It is changed by the functions creat and read. 


The st_mtime member is the date/time when the file was ‘last 
modified. It is changed by the functions creat and write. 


The st_ctime member is the d 
created. It is changed by t 
and write. 


te/time when the file was 
e fin 


a 
h unctions creat, link, unlink, 


Information is not available in the members st_ino, st_nlink, 
and st_size. 


The fstat function fails if: 


e The fildes argument is not a valid open file 
descriptor [EBADF]. 


e The buf argument points to an invalid address 
[EFAULT]. 


RETURN VALUE: 

Upon successful completion a value of 0 is returned. 
Otherwise, a value of -l is returned and errno is set to 
indicate the error. 


RELATED FUNCTIONS: 


creat, link, stat, time, unlink. 
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fwrite 
Buffered output. 
SYNTAX: 
# include <stdio.h> 
fwrite (buf_ptr, size, nitems, file) 
int size; 
int nitems; 
char *buf_ptr; 
FILE *file; 
ARGUMENTS ; 
buf ptr 
Buffer address pointer. 
size 
Item size in characters. 
nitems 
Number of items to write. 
file 
File pathname. 
DESCRIPTION: 
The fwrite function appends at most nitems of size size 
beginning at buf_ptr to the named output file. It returns 
the number of items actually written. 


RELATED FUNCTIONS: 


fopen, fread, gets, printf, putc, puts, read, scanf, 
write. 
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qcvt 
Output conversion. 
SYNTAX: 
char *gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 
ARGUMENTS : 
value 
Value to be converted. 
ndigit 
Number of significant digits. 
buf 
Pointer to output string. 
DESCRIPTION: 
The gcvt function converts the argument value to a 
null-terminated string pointed to by buf and returns buf. It 
attempts to produce ndigit significant digits in FORTRAN 
F-format if possible; otherwise it produces output in 
E-format, ready for printing. Trailing zeros are suppressed. 


NOTE 


The return values point to static data whose con- 
tents are overwritten by each call. 


RELATED FUNCTIONS: 


ecvt, fcvt, printf. 
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getc 
Gets character from file. 
SYNTAX: 
# include <stdio.h> 


int getc (file) 
FILE *file; 


ARGUMENTS: 
file 

File pathname. 
DESCRIPTION: 
The getc function returns the next character from the buffer 
associated with the named input file. The function obtains a 
new buffer's worth of characters whenever all the characters 
have been returned. 


DIAGNOSTICS: 


This function returns the value -l when it encounters the end 
of a file. 


NOTE 


Because it iS a macrocall, getc treats incorrectly 
a file argument with side effects; for example: 


getc(*f++); 
RELATED FUNCTIONS: 


ferror, fgetc, fopen, fread, getchar, gets, getw, putc, 
scanf. 
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getchar 
Gets character from stdin file. 
SYNTAX: 
# include <stdio.h> 
int getchar ( ) 
ARGUMENTS: 
None. 
DESCRIPTION: 
The getchar function is identical to getc(stdin). This 
function is implemented as a macrocall; it cannot be 
redefined. 


DIAGNOSTICS: 


This function returns the value -1l1 when it encounters. the end 
of a file. | 


RELATED FUNCTIONS: 


ferror, fgetc, fopen, fread, getc, gets, getw, putc, 
scanf. 
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getcwd 
Get current working directory. 
SYNTAX: 
char *getcwd (buf, size) 
char *buf; 
int s1ze; 
ARGUMENTS : 
buf 
Returned current working directory string. 
size 
Buffer size in characters. 


DESCRIPTION: 


The getcwd function returns a pointer to the null-terminated 
character string of the current working directory. 


The value of the size argument must be at least one character 
longer than the pathname to be returned. Under Multics, the 
maximum length of a directory path is 168 characters. 

If the buf argument is a null pointer, getcwd obtains size 
characters of space using the malloc function. In this case, 
you can use the returned pointer in a subsequent call to the 
free function. 


If the buf argument is not a null pointer, the string is 
placed in buf, and the pointer to buf is returned. 


DIAGNOSTICS: 


If an error occurs, a null pointer is returned. 
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getenv 


Get environment name. 
SYNTAX : 


char *getenv (name) 
char *name; 


ARGUMENTS : 
name 
Environment name. 
DESCRIPTION: 
The getenv function searches the environment list for a 
String of the form name and returns a pointer to that value 


if such a string is present; otherwise, it returns a null 
pointer. 
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getgid 
Get real group ID. 
SYNTAX: 
int getgid ( ) 
ARGUMENTS : 
None. 
DESCRIPTION: 


The getgid function returns the real group ID of the calling 
process. 


RELATED FUNCTIONS: 


getuid. 


4-104 HHO7-01 


getlogin 


getlogin 


Get login name. 
SYNTAX 3 
char *getlogin ( ); 
ARGUMENTS : 
None. 
DESCRIPTION: 


The getlogin function returns a pointer to a static string 
containing the login name of the calling process. 


DIAGNOSTICS: 


This function returns a null pointer if the name is not 
found. 
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getopt 
Get option letter from argument. 
SYNTAX: 


int getopt (argc, argv, optstring) 
int argc; 

char **argv; 

char *optstring; 

extern char *optarg; 

extern int optind; 


ARGUMENTS: 
argc 

Index into *argv. 
argv 

Input string of options. 
optstring 

String of valid options. 
DESCRIPTION: 
The getopt function returns the next option ietter in argv 
that matches a letter in optstring. The argument optstring 
is a string of recognized option letters; if a letter is 
followed by a colon, the option is expected to have an 
argument that may or may not be separated from it by white 
space. The pointer optarg is set to point to the start of 
the option argument on return from getopt. 
The getopt function places in optind the argv index of the 
next argument to be processed. Because optind is external, 
it is normally initialized to zero automatically before the 
first call to getopt. 
RETURN VALUE: 
When all options have been processed (that is, up to the 
first nonoption argument), getopt returns EOF. The special 


option minus (-) can be used to delimit the end of the 
options; EOF is returned, and minus (-) is skipped. 
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DIAGNOSTICS: 


The getopt function displays an error message and returns a 
question mark (?) when it encounters an option letter not 
included in optstring. 


EXAMPLE : 
The following code fragment shows how one might process the 
arguments for a command that can take the mutually exclusive 


options a and b, and the options f and e, both of which 
require arguments: | 
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main (argc, argv} 
int argc; 
char **argv; 


int c; 
extern int optind; 
extern char *optarg; 


while ((c = getopt (argc, argv, "“abf:o:")) != EOF) 
switch (c) { | 


case "a": 
if (bfq) 
errfgt+; 
else 
afg+t; 
break; 
case "b": 
if (afg) 
errfg++; 
else 
bproc(); 
break; 
case "ff": 
ifile = optarg; 
break; 


case "o"; 
ofile = optarg; 
bufsize = 512; 
break; 

case "?": 
errfgtt+; 


} 
if (errfg) { 
fprintf (stderr, "“usage:..."); 
exit; 


for ( ; optind < argc; optind++) { 
if (access (argv[optind], 4)) { 


} 


nen! @ 2 » 
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getpid 
Get process ID. 
SYNTAX: 
getpid ( ) 
ARGUMENTS : 
None. 
DESCRIPTION: 


The getpid function returns the process ID of the calling 
process. 
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qets 


Gets string from stdin file. 
SYNTAX: 
# include <stdio.h> 


char *gets (s) 
char *s; 


ARGUMENTS : 
s 

Pointer to buffer that will hold string. 
DESCRIPTION: 
The gets function reads a string into s from the standard 
input file stdin. The string is terminated by a newline 
character, which is replaced in s by a null character. The 
gets function returns its argument. 


DIAGNOSTICS: 


The gets function returns a null pointer if it encounters the 
end of a file or an error. 


The gets function deletes the newline character 
ending its input. 


RELATED FUNCTIONS: 


ferror, fgets, fopen, fread, getc, puts, Scan. 
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getuid 
Get real user ID. 
SYNTAX: 
int getuid ( ) 
ARGUMENTS : 
None. 
DESCRIPTION: 


The getuid function returns the real user ID of the calling 
process. | 


RELATED FUNCTIONS: 


getgid. 
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getw 
Gets word from file. 
SYNTAX 3 
# include <stdio.h> 


int getw (file) 
FILE *file; 


ARGUMENTS : 
file 

File pathname. 
DESCRIPTION: 
The getw function returns the next word from the named input 
file. It returns the constant EOF when it encounters the end 
of a file or an error, but since that is a valid integer 
value, feof and ferror should be used to check the success of 
getw. The getw function assumes no special alignment in the 
file. 
DIAGNOSTICS: 


This function returns the value -1l when it encounters the end 
of a file. 


RELATED FUNCTIONS: 


feof, ferror, fgetc, fopen, fread, getc, getchar, gets, 
putc, putw, scanf. 
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qmt ime 
Convert date and time to ASCII. 
SYNTAX : 


struct tm *qmtime (clock) 
lona *clock; 


ARGUMENTS : 
clock 

Military time. 
DESCRIPTION: 
The gmtime function returns a pointer to a structure | 
containing the components of the time. The gmtime function 
converts directly to Greenwich Mean Time (GMT). 


The structure declaration from the include file is: 


struct tm { 


int tm_sec; 
int tm_min; 
int tm_hourj; 
int tm_mday; 
int tm_mon; 
int tm_year; 
int tm_wday; 
int tm_yday; 
int tm_isdst; 


es 


These quantities give the time on a 24-hour clock, day of 
month (1-31), month of year (0-11), day of week (Sunday - 0), 
year - 1900, day of year (0-365), and a flag that is nonzero 
if daylight savings time is in effect. 


The external long variable timezone contains the difference, 
in seconds, between GMT and local standard time (in EST, 
timezone is 5*60*60); the external variable daylight is 
nonzero if, and only if, the standard U.S. daylight savings 
time conversion should be applied. 
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NOTE 


The return values point to static data whose con- 
tents are overwritten by each call. 


RELATED FUNCTIONS: 


asctime, ctime, localtime, time, tzset. 
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hypot 


Euclidean distance. 
SYNTAX : 
# include <math.h> 


double hypot (x, y) 
double x, y; 


ARGUMENTS : 
x 


Double-precision value.. 


Double-precision value. 
DESCRIPTION: 
The hypot function returns 
(x2 + y?) 
taking precautions against unwarranted overflows. 
RELATED FUNCTIONS: 


sqrt. 
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Control device. 
SYNTAX: 
ioctl (fildes, request, arg) int fildes, request; 
ARGUMENTS : 
fildes 
A file descriptor. 
request 
One of the request types described below. 
arg 


Either a pointer to the termio structure (see below), or 
an integer, depending on the request type. 


DESCRIPTION: 
NOTE 

The Multics implementation of ioctl is incomplete. 
ioctl performs a variety of functions on stdin, stdout, and 
stderr. Although the mode settings have been translated as 
closely as possible to Multics mode settings, there may be a 
difference in the actual actions taken. It is suggested that 
the user create an intermediate to call the specific I/O 
module with the desired functionality. 
ioctl will fail if one or more of the following are true: 


e fildes is not a valid open file descriptor [EBADF]. 


e fildes is not associated with stdin, stdout and stderr 
[ENOTTY]. 


e Request or arg is not valid [EINVAL]. 
RETURN VALUE: 


If an error has occurred, a value of -l is returned and errno 
is set to indicate the error. 
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1. 


The primary ioctl system calls have the form: 

ioctl (fildes, request, arg) struct termio *arg; 
The requests using this form are: 
TCGETA 


Get the parameters associated with the terminal and 
store in the termio structure referenced by arg. 


TCSETA 
Set the parameters associated with the terminal from 
the structure referenced by arg. The change is 
immediate. 

TCSETAW 
Wait for the output to drain before setting the new 
parameters. Use this form when changing parameters 
that will affect output. . 

TCSETAF 


Wait for the output to drain, then flush the input 
queue and set the new parameters. 


Additional ioctl calls have the form: 
ioctl (fildes, request, arg) int arg; 

The requests using this form are: 

TCSBRK 


Wait for the output to drain. If arg is 0, then send 
a break (zero bits for 0.25 seconds.) 


TCFLSH 
If arg is 0, flush the input queue; if 1, flush the 


output queue; if 2, flush both the input and output 
queues. 
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SPECIAL CHARACTERS: 
ERASE (#) 


Erases the preceding character. It will not erase 
beyond the start of a line, as delimited by a NL, 
EOF, or EOL character. 


KILL (@) 


Deletes the entire line, as delimited by a NL, EOF, 
or EOL character. 


EOF (control-d or \F) 


May be used to generate an end-of-file from a 
terminal. When received, all the characters waiting 
to be read are immediately passed to the program, 
without waiting for a new-line, and the EOF is 
discarded. Thus, if there are no characters waiting, 
which is to say the EOF occurred at the beginning of 
a line, zero characters will be passed back, which is 
the standard end-of-file indication. 


NL (ASCII LF) 


The normal line delimiter. It cannot be changed or 
escaped. 


STOP (Control-s or ASCII DC3) 
Used to temporarily suspend output. It is useful 
with CRT terminals to prevent output from 
disappearing before it can be read. 

START (Control-q or ASCII DCl) 
Used to resume output that has been suspended by a 
STOP character. While output is not suspended, START 


characters are ignored and not read. The start/stop 
characters cannot be changed or escaped. 
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TERMIO STRUCTURE: 

Several ioctl system calls apply to terminal files. The 
primary calls use the following structure, defined in 
<termio.h>: 


#define NCC 8 


struct termio j 

int c_iflag; /* input modes */ 

int c_oflag; /* output modes */ 
int c_cflag; /* control modes */ 
int c_lflag; /* local modes */ 
char c_line; /* line discipline */ 
unsigned char c_cc{NCC]; /* control chars */ 


i 


. The special control characters are defined by the array c_cc. 
The relative positions and individual values for each 
function are as follows: 


VINTR 

VQUIT 

VERASE — # 
VKILL @ 
VEOF EOT . 
VEOL 

reserved 

switch 


NOON PWNHH.O 


The c_iflag field describes the basic terminal input control: 


IGNBRK 0000001 Ignore break condition. 

BRKINT 0000002 Signal quit on break. 

ISTRIP 0000040 Strip character. 
-INLCR 0000100 Map NL to CR-NL on input. 

IUCLC 0001000 Map uppercase to lowercase on input. 
IXON 0002000 Enable start/stop output control. 
IXOFF 0010000 Enable start/stop input control. 


If IGNBRK is set, the break condition (a character framing 
error with data all zeros) is ignored, that is, not put on 
the input queue and therefore not read by any process. 
Otherwise if BRKINT is set, the break condition will generate 
a quit signal. | | 


If ISTRIP is set, valid characters are first stripped to 
7-bits, otherwise all 8-bits are processed. 


If INLCR is set, a received NL character is translated into a 
CR character. 
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If IUCLC is set, a received uppercase alphabetic character is 
translated into the corresponding lowercase character. 


If IXON is set, start/stop output control is enabled. A 
received STOP character will suspend output and a received 
START character will restart output. 


If IXOFF is set, the system will transmit START/STOP 
characters when the input queue is nearly empty/full. 


The initial input control value is defined by the initial 
setting for the terminal type on Multics. 


The c_oflag field specifies the system treatment of output: 


OPOST 0000001 Postprocess output. 
OLCUC 0000002 Map lowercase to uppercase on output. 
ONLCR 0000004 Map NL to CR-NL on output. 


If OPOST is set, output characters are post-processed as 
indicated by the remaining flags, otherwise characters are 
transmitted without change. 


If OLCUC is set, a lowercase alphabetic character is 
transmitted as the corresponding uppercase character. This 
function is often used in conjunction with IUCLC. 


set, the NL character is transmitted as the CR-NL 


The initial output control value is defined by the initial 
setting for the terminal type on Multics. 


The c_cflag field is unused and set to 9 on Multics. 


The c_lflag field of the argument structure is used by the 
line discipline to control terminal functions: 


ISIG 0000001 Enable signals. 

ICANON 0000002 Canonical input (erase and kill processing). 
ECHO 0000010 Enable echo. 

ECHONL 0000100 &Echo NL. 


If ISIG is set, each input character is checked against the 
special control characters INTR, and QUIT. If an input 
character matches one of these control characters, the 
function associated with that character is performed. 
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If ICANON is set, canonical procesSing is enabled. This 
enables the erase and kill edit functions, and the assembly 
of input characters into lines delimited by NL and EOF. If 
ICANON is not set, read requests are satisfied directly from 
the input queue. A read will not be satisfied until at least 
MIN characters have been received. This allows fast bursts 
of input to be read efficiently while still allowing single 
character input. 

If ECHO is set, characters are echoed as received. 

When ICANON is set, the following echo functions are 
possible. If ECHONL is set, the NL character will be echoed 
even if ECHO is not set. This is useful for terminals set to 
local echo (so-called half duplex). 


The c_line is unused with a value of '\0' on Multics. 
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isalnum 
Character classification (alphanumeric). 
SYNTAX: 
# include <ctype.h> 


int isalnum (c) 
int c; 


ARGUMENTS: 
Cc 

Single-character value. 
DESCRIPTION: 
The isalnum macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isalnum function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF (see isascii8). The function is nonzero 
if c is an alphanumeric (letter or digit). 
RELATED FUNCTIONS: 


isalpha, isascii, iscntrl, isdigit, islower, isprint, 
ispunct, isspace, isupper, isxdigit. 
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isalpha 
Character classification (alphabetic). 
SYNTAX: 
# include <ctype.h> 


int isalpha (c) 
int c; 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The isalpha macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isalpha function is 
defined only where isascii8 is true and on the single. 


non-ASCII value EOF. The function is nonzero if c is a 
letter. 


isalnum, isasScii, iscntrl, isdigit, islower, isprint, 
ispunct, isspace, isupper, isxdigit. | 
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isascii 
Character classification (7-bit ASCII). 
SYNTAX: 
# include <ctype.h> 


int isascii (c) 
int c; 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The isascii macrocall classifies 7-bit ASCII-coded integer 
values by table lookup. The macrocall is a predicate 
returning nonzero for true, zero for false. The isascii 
function is defined on all integer values. The function is 
nonzero if c is a 7-bit ASCII character, that is, a 
non-negative integer less than hexadecimal 80. 
RELATED FUNCTIONS: 


isalnum, isalpha, iscntrl, isdigit, islower, isprint, 
ispunct, isspace, isupper, isxdigit. 
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isatty 


Determines if association is to a terminal. 
SYNTAX: 
int isatty (fildes) 
int fildes; 
ARGUMENTS : 
fildes 
File descriptor. 
DESCRIPTION: 


The isatty function returns 1 if fildes is associated with a 
terminal device; otherwise, it returns a 0. 
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iscntrl 
Character classification (control character). 
SYNTAX: 
# include <ctype.h> 


int iscntrl (c) 
int c; 


ARGUMENTS: 
Cc 

Single-character value. 
DESCRIPTION: 
The iscntrl macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The iscntrl function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is a 
delete character (hexadecimal 7F) or ordinary control 
character (hexadecimal 0 through 17, 84 through 97, and 9B 
through 9F). 
RELATED FUNCTIONS: 


isalnum, isalpha, isascii, isdigit, islower, isprint, 
ispunct, isspace, isupper, isxdigit. 
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isdigit 
Character classification (digit). 
SYNTAX: 
# include <ctype.h> 


int isdigit (c) 
int c; 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The isdigit macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isdigit function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is a digit 
[0 through 9]. 


ELATED FUNCTIONS: 


) 


isalnum, isalpha, isascii, iscntrl, islower, isprint, 
ispunct, isspace, isupper, isxdigit. 
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islower 
Character classification (lowercase alphabetic). 
SYNTAX: 
# include <ctype.h> 


int islower (c) 
int c; 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The islower macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The islower function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is a 
lowercase letter. The lowercase letters are hexadecimal 61 
through 7A, EO through F6, and F8 through FF. 
RELATED FUNCTIONS: 


isalnum, isaipha, isasScil, iscntri, isdigit, isprint, 
ispunct, isspace, isupper, isxdigit. 
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isprint 
Character classification (printing character). 
SYNTAX: 
# include <ctype.h> 


int isprint (c) 
int c; 


ARGUMENTS: 
Cc 

Single-character value. 
DESCRIPTION: 
The isprint macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isprint function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is a 
printing character; that is, hexadecimal 20 (space) through 
7E (tilde), or hexadecimal AO (no-break space) through FF 
(small letter y with diaeresis). 
RELATED FUNCTIONS: 


isalnum, isalpha, isascii, iscntrl, isdigit, islower, 
ispunct, isspace, isupper, isxdigit. 
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ispunct 
Character classification (punctuation character). 
SYNTAX: 
# include <ctype.h> 


int ispunct (c) 
int c; 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The ispunct macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The ispunct function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is a 
punctuation character (neither control nor alphanumeric). 
RELATED FUNCTIONS: 


isalnum, isalpha, isascii, iscntrl, isdigit, islower, 
isprint, isspace, isupper, isxdigit. 
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isspace 
Character classification (whitespace character). 
SYNTAX: 
# include <ctype.h> 


int isspace (c) 
int c; 


ARGUMENTS ; 
Cc 

Single-character value. 
DESCRIPTION: 
The isspace macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isspace function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is a 
space, tab, carriage return, newline character, vertical tab, 
formfeed, or no-break space. 
RELATED FUNCTIONS: 


isalnum, isalpha, isascii, iscntrl, isdigit, islower, 
isprint, ispunct, isupper, isxdigit. 
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isupper 
Character classification (uppercase alphabetic). 
SYNTAX: | 
# include <ctype.h> 


int isupper (c) 
Int Cc: 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The isupper macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isupper function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF. The function is nonzero if c is an 
uppercase letter. The uppercase letters are hexadecimal 41 
through 5A, CO through D6, and D8 through DE. 


RELATED FUNCTIONS: 
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isxdigit 
Character classification (hexadecimal). 
SYNTAX: 
# include <ctype.h> 


int isxdigit (c) 
int c; 


ARGUMENTS : 
Cc 

Single-character value. 
DESCRIPTION: 
The isxdigit macrocall classifies ASCII-coded integer values 
by table lookup. The macrocall is a predicate returning 
nonzero for true, zero for false. The isxdigit function is 
defined only where isascii8 is true and on the single 
non-ASCII value EOF (see isascii8)}. The function is nonzero 
if c is a hexadecimal digit ({0 through 9], [A through F], or 
[a through f]). 
RELATED FUNCTIONS: 


isalnum, isalpha, isascii, iscntrl, isdigit, islower, 
isprint, ispunct, isspace, isupper. 
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Sends a signal to a process. 
SYNTAX: 


int kill (pid, sig) 
int pid, sig; 


ARGUMENTS : 
pid 

Process ID to be signaled (ignored). 
Sig 

Signal to be sent. 
DESCRIPTION: 
The kill function signals the passed signal to the current 
process according to actions specified by any previous calls 
to Signal. Any signals not defined cause a -1l to be 
returned. The process id is ignored. 


RELATED FUNCTIONS: 


Signal. 
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idexp 
Exponential function. 
SYNTAX: 
double ldexp (value, exp) 
double value; 
int exp; 
ARGUMENTS : 
value 
Double-precision value. 
exp 
Exponent. 
DESCRIPTION: 
The ldexp function returns the quantity value*2©xP, 
RELATED FUNCTIONS: 


frexp, modf. 
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Link to a file. 
SYNTAX: 


int link (path), path?) 
char *path,, *path?; 


ARGUMENTS : 
pathy} 
Pathname of an existing file. 
path? 
Pathname of the new directory entry to be created. 
DESCRIPTION: 


The link function creates a new link (directory entry) for an 
existing file. 


The link function fails and no link is created if: 


e A component of either path prefix is not a directory 
[ENOTDIR]. 


* A component of either path prefix does not exist 
{[ENOENT ]. 


@ A component of either path prefix denies search access 
[EACCES]. 


e The file named by path] does not exist [ENOENT]. 
e The link named by path? exists [EEXIST]. 
e Pointer pathz points to a null pathname [ENOENT]. 


e The requested link requires writing in a directory 
without write access [EACCES]. 
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RETURN VALUE: 

Upon successful completion, a value of 0 is returned. 
Otherwise, a value of -1 is returned and the variable errno 
is set to indicate the error. 

RELATED FUNCTIONS: 


unlink. 
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localtime 
Convert date and time to ASCII. 
SYNTAX: 
# include <time.h> 


struct tm *localtime (clock) 
long *clock; 


ARGUMENTS: 
clock 


Long integer pointer to the time in seconds since Jan. l, 
1970 (such as returned by time). 


DESCRIPTION: 

The localtime function returns a pointer to a structure 
containing the components of the time. The localtime 
function corrects for the time zone and possible daylight 
savings time. 

The structure declaration from the include file is: 


struct tm { 


int tm_sec; 
int tm_min; 
int tm_hour; 
int tm_mday; 
int tm_mon; 
int tm_year; 
int tm_wday; 
int tm_yday; 
int tm_isdst; 


i 


These quantities give the time on a 24-hour clock, day of 
month (1-31), month of year (0-11), day of week (Sunday - 0), 
year - 1900, day of year (0-365), and a flag that is nonzero 
if daylight savings time is in effect. 


The external long variable timezone contains the difference, 
in seconds, between GMT and local standard time (in EST, 
timezone is 5*60*60); the external variable daylight is 
nonzero if and only if the standard U.S. daylight savings 
time conversion should be applied. 
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NOTE 


The return values point to static data whose con- 
tents are overwritten by each call. 


RELATED FUNCTIONS: 


asctime, ctime, gmtime, time, tzset. 
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log 
Natural logarithm function. 
SYNTAX: 
# include <math.h> 


double log (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value. 
DESCRIPTION: 


The log function returns the natural logarithm of x. X must 
be positive. 


DIAGNOSTICS: 


The log function returns a huge negative value and sets errno 
to EDOM when x is nonpositive. 


RELATED FUNCTIONS: 


exp, hypot. logl0, pow, sinh, sart. 
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logl10 


Common logarithm function. 
SYNTAX: 
# include <math.h> 


double logl0 (x) 
Gouble x; 


ARGUMENTS ; 
x 

Double-precision value. 
DESCRIPTION: 


The logl0 function returns the common logarithm of x. X must 
be positive. 


DIAGNOSTICS: 


The log function returns a huge negative value and sets errno 
to EDOM when x is nonpositive. 


RELATED FUNCTIONS: 


exp, hypot, log, pow, sinh, sqrt. 
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long jmp 

Non-local goto. 

SYNTAX: 
# include <setjmp.h> 
void longjmp (env, val) 
jmp_buf env; 
int val; 

ARGUMENTS : 


env 


Pointer to a label structure set by a previous call to 
setjmp. 


val 
Value to be returned. 
DESCRIPTION: 


The longjmp function restores the environment saved by the 
most recent call to setjmp having env as itS argument. It 
then returns in such a way that execution continues as if the 
call to setjmp had returned with the value val instead of 
zero (as is the case with the true return from setjmp). The 
function that called setjmp must not itself have returned in 
the interim. If longjmp is invoked with a val argument of 
zero, it behaves as if 1 had been used instead. 


RELATED FUNCTIONS: 


kill, setjmp, signal. 
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malloc 
Heaps memory allocator. 
SYNTAX: 


char *malloc (size) 
unSigned int size; 


ARGUMENTS : 
size 

Size of the desired memory block in characters. 
DESCRIPTION: 
The malloc function is part of a general-purpose heap memory 
allocation package. The malloc function returns a character 
pointer to the beginning of a double-word-aligned block of at 


least size characters. Such blocks are suitable for storing 
objects of any type. 


The heap is managed by the C functions malloc, calloc, 
realloc, and free. 


The heap consists of one or more areas, each consisting of 
one or more segments. Heap areaS are expanded, or new areas 
are created, as the need arises. 

DIAGNOSTICS: 

If the heap does not contain enough memory and cannot be 
sufficiently expanded to meet the request, the variable errno 
is set to ENOMEM or ENOSPC and a null character pointer is 
returned. 

RELATED FUNCTIONS: 


calloc, free, realloc. 
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memccpy 


Memory-to-memory copy. 

SYNTAX: 
# include <memory.h> 
unsigned char *memccpy (Sj, S2, Cc, n) 
unsigned char *s], *s?2; 


unsigned char c; 
int n; 


ARGUMENTS : 
Sl 

Pointer to target memory area (output). 
S2 


Pointer to source memory area (input). 


Cc 

Last character to copy (if found in s9). 
n 

Number of characters to copy. 
DESCRIPTION: 


The memccpy function copies characters from memory area s2 
into sj, stopping after the first occurrence of character c 
has been copied, or after n characters have been copied, 
whichever comes first. If n is less than or equal to zero, 
no characters are copied. 


This function operates efficiently on memory areas (arrays of 
characters bounded by a count, not terminated by a null 
character). This function does not check for the overflow of 
any receiving memory area. 
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RETURN VALUE: 
This function returns a pointer to the character after the 
copy of c in sj, or (unsigned char *) 0 if c was not found in 
the first n characters of s2. 
NOTE 
This function is declared in the <memory.h> 
header file. 


RELATED FUNCTIONS: 


memchr, memcmp, memcpy, memset, umemchr, umemcmp, 
umemcpy, umemset. 
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memchr 
Locates character in memory. 
SYNTAX: 
# include <memory.h> 
unsigned char *memchr (s, c, n) 


unsigned char *s; 
unsigned char c; 


int n; 
ARGUMENTS : 
s 
Pointer to memory area to check. 
Cc 
Character to seek. 
n 
Size of memory area in characters. 
DESCRIPTION: 
The memchr func returns &@ pointer to the St occurrence 


emcnr tion fi 
of character c within the first n characters of memory area 
s, or (unsigned char *) 0 if c does not occur. 


This function operates efficiently on memory areas (arrays of 
characters bounded by a count, not terminated by a null 
character). 

NOTE 


This function is declared in the <memory.h> 
header file. 


RELATED FUNCTIONS: 


memccpy, memcmp, memcpy, memset, umemchr, umemcmp, 
umemcpy, umemset. 
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meimemp 


memcmp. 


Memory-to-memory compare. 
SYNTAX: 
# include <memory.h> 


int memcmp (sj, S2, Nn) 
unsigned char *s}, *S2; 


int n; 
ARGUMENTS : 
sl 

Pointer to first memory area to be compared. 
$2 

Pointer to second memory area to be compared. 
n 


Size of memory areas in characters. 
DESCRIPTION: 


The memcmp function compares its arguments, looking at the 
first n characters only. 


This function operates efficiently on memory areas (arrays of 
characters bounded by a count, not terminated by a null 
character). It executes without a stack frame of its own, 
and it makes use of commercial instructions. 


RETURN VALUE: 
This function returns an integer less than, equal to, or 
greater than zero, depending on whether sj is less than, 


equal to, or greater than sz. If n is less than or equal to 
zero, equality is indicated. 
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NOTES 


1. This function is declared in the <memory.h> 
header file. 


2. The memcmp function uses 8-bit ASCII 
comparisons. Comparison proceeds from left 
to right until an unequal pair of characters 
is found or until all characters have been 
compared without finding an unequal pair. If 
an unequal pair is found, their ordering in 
the 8-bit ASCII code set determines the 
ordering of the two operands. 


RELATED FUNCTIONS: 


memccpy, memchr, memcpy, memset, umemchr, umemcmp, 
umemcpy, umemset. 
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memcpy 
Memory-to-memory copy. 
SYNTAX: 
# include <memory.h> 


unsigned char *memcpy (sj, S2, n) 
unsigned char *s}, *S?; 


int n; 
ARGUMENTS ; 
Sl] 

Pointer to target memory area (output). 
$2 

Pointer to source memory area (input). 
n 


Number of characters to copy. 
DESCRIPTION: 


The memcpy function copies n characters from memory area s2 
to sj. 


This function operates efficiently on memory areas (arrays of 
characters bounded by a count, not terminated by a null 
character). This function does not check for the overflow of 
any receiving memory area. It executes without a stack frame 
of its own. 


RETURN VALUE: 
This function returns s}. 
NOTES 


1. This function is declared in the <memory.h> 
header file. 


2. The memcpy function produces unspecified 


results if the memory areas overlap but are 
not identical. 
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memset 
Initializes memory. 
SYNTAX: 
# include <memory.h> 
unsigned char *memset (s, c, n) 


unsigned char *s; 
unsigned char c; 


int n; 
ARGUMENTS : 
s 

Pointer to memory area to initialize. 
Cc 

Character to fill memory area. 
n 

Size of memory area in characters. 
DESCRIPTION: 


area s to the value of character c. If n is less than or 
equal to zero, no characters are set. 


This function operates efficiently on memory areas (arrays of 
characters bounded by a count, not terminated by a null 
character). This function does not check for the overflow of 
any receiving memory area. It executes without a stack frame 
of its own, and it makes use of commercial instructions. 
RETURN VALUE: 
This function returns *s. 

NOTE 


This function is declared in the <memory.h> 
header file. 


4-150 HH07-01 


mktemp 
Makes a unique file name. 


SYNTAX: 


char *mktemp (template) 
char *template; 


ARGUMENTS : 
template 
Template character string plus six trailing Xs. 
DESCRIPTION: 
The mktemp function replaces template by a unique file name, 
and returns the address of the template. The template should 
look like a file name with six trailing Xs, which will be 
replaced with a unique string. The letter is chosen so that 
the resulting name does not duplicate an existing file. 
NOTE 
It is possible to run out of letters. 


RELATED FUNCTIONS: 


getpid. 
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modf 
Return fraction part of value. 
SYNTAX: 


double modf (value, iptr) 
double value, *iptr; 


ARGUMENTS : 
value 
Double-precision value. 
iptr 
Pointer to integer part of value. 
DESCRIPTION: 


The modf function returns the signed fractional part of value 
and stores the integer part indirectly, through iptr. 


RELATED FUNCTIONS: 


frexp, ldexp. 
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open 
Opens for reading or writing. 
SYNTAX: 
# include <stdio.h> 
int open (path, oflag) 
char *path; 
int oflag; 
ARGUMENTS : 
path 
Pathname of file to open. 
oflag 
Access flag (see below). 
DESCRIPTION: 
The open function opens a file descriptor for the named file 
and sets the file status flags according to the value of 
oflag. The path pointer refers to a pathname naming a file. 


Oflag values are constructed by performing a logical OR 
operation on flags from the following list: 


O_RDONLY -- Open for reading only. 
O_WRONLY -- Open for writing only. 
' O_RDWR -- Open for reading and writing. 
O_CREAT -~ Create a new file. If the file already 
exists, this flag has no effect. 
O_EXCL -~ Only meaningful in combination with O_CREAT; 


these flags together specify that the file 
must not already exist. 


The file pointer 


(used to mark the current position within 
the file) is set 


to the beginning of the file. 


This function also works with dynamic and device files. To 
open an interactive device file (such as a terminal), use the 
O_RDWR flag; to open a noninteractive device file (such as a 
printer), use O_RDONLY or O_WRONLY, aS appropriate. 
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No process can have more than 20 file descriptors open 
simultaneously. 


The open function does not allocate a buffer until it is 
needed. 


RETURN VALUE: 

Upon successful completion, a file descriptor (a nonnegative 
integer) is returned. Otherwise, a value of -1 is returned 
and the variable errno is set to indicate the error returned 
from Multics. 

RELATED FUNCTIONS: 


close, creat, dup, fcntl, read, write. 
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perror 


System error messages. 
SYNTAX: 


void perror (s) 
char *s; 


extern int errno; 

extern cahr *sys_errlist[ ]; 

extern int sys_nerr; 
ARGUMENTS : 
s 

A pointer to a message string. 
DESCRIPTION: 


Perror produces a message on the standard error output, 
describing the last error encountered during a call to a 
system or library function. The argument string s is printed 
first, then the message and a new-line. To be of most use, 
the argument string should include the name of the program 
that incurred the error. The error number is taken from the 
external variable errno, which is set when errors occur but 
not cleared when non-erroneous calls are made. 


To simplify variant formatting of messages, the array of 
message strings sys_errlist is provided; errno can be used as 
an index in this table to get the message string without the 
new-line. Sys_nerr is the largest number provided for in the 
table; it should be checked because new error codes may be 
added to the system before they are added to the table. 
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pow 


Power function. 
SYNTAX : 
# include <math.h> 


double pow (x, y) 
double x, jy; 


ARGUMENTS : 
xX, Y 

Double-precision values. 
DESCRIPTION: 
The pow function returns xY. The values of x and y cannot 
both be zero. If x is less than or equal to zero, y must be 
an integer. 
DIAGNOSTICS: 
The pow function returns a huge value when the correct value 
would overflow. A truly Ont negeous argument can also result 
in errno being set to ERANGE. 
The pow function returns a huge negative value and sets errno 
to EDOM when x is nonpoSitive and y is not an integer, or 
when x and y are both zero. 


RELATED FUNCTIONS: 


exp, hypot, log, sinh, sqrt. 
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printf 
Formats output. 
SYNTAX: 
# include <stdio.h> 


int printf (format [, arg] ... ) 
char *format; 


ARGUMENTS : 
format 
Format string. 
arg 
Optional argument to be printed. 
DESCRIPTION: 
The printf function writes output to the user-out file. It 
is equivalent to a call to fprintf with the argument stdout 


inserted before the arguments to fprintf. 


For more information on this function, refer to the 
description of fprint. 


RELATED FUNCTIONS: 


ecvt, fprintf, putc, scanf, sprintf. 
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putc 
Puts a character on a file. 
SYNTAX: 
# include <stdio.h> 
int putc (c, file) 
char c; 
FILE *file; 
ARGUMENTS : 
Cc 
Character to be appended to the file. 
file 
File pathname. 
DESCRIPTION: 
The putc function appends the character c to the buffer 
associated with the named output file, writing the buffer 
whenever it is full. 
RETURN VALUE: 
The putc function returns the character appended. 
DIAGNOSTICS: 
This function returns the constant EOF when it encounters an 
error. Since this is a good integer, ferror should be used 
to detect putw errors. 
NOTE 
Because it is a macrocall, putc treats incorrectly 
a file argument with side effects, for example, 
putc(c, *f++); . 


RELATED FUNCTIONS: 


ferror, fopen, fputc, fwrite, getc, printf, putchar, 
puts, putvw. 
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putchar 
Puts character on stdout file. 
SYNTAX: 
# include <stdio.h> 
putchar (c) 
ARGUMENTS : 
Cc 
Character to be appended to the file. 
DESCRIPTION: 
The putchar(c) function is defined as putc(c, stdout). 
DIAGNOSTICS: | 
This function returns the constant EOF when it encounters an 
error. Since this is a good integer, ferror should be used 
‘to detect putw errors. | ss 
RELATED FUNCTIONS: 


ferror, fopen, fputc, fwrite, getc, printf, putc, puts, 
putw. 
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puts 


Puts string on stdout file. 
SYNTAX 3 
# include <stdio.h> 


int puts (s) 
char *s; 


ARGUMENTS : 
s 

String to be written to the file. 
DESCRIPTION: 


The puts function copies the null-terminated string s to the 
user-out file and appends a newline character. 


This function does not copy the terminating null character. 
DIAGNOSTICS: | 
This function returns EOF on error. 
NOTE 
The puts function appends a newline character. 
RELATED FUNCTIONS: 


ferror, fflush, fopen, fputs, fwrite, gets, printf, putc. 
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putw 
Puts a word on a file. 
SYNTAX: 
# include <stdio.h> 
putw (w, file) 
int w; 
FILE *file; 
ARGUMENTS : 
Ww 
Integer to be written to the file. 
file 
File pathname. 
DESCRIPTION: 
The putw function appends the integer w to the output file. 
The putw function neither assumes nor causes special 
alignment in the file. 
DIAGNOSTICS: 
This function returns the constant EOF when it encounters an 
error. Since this is a good integer, ferror should be used 
to detect putw errors. 


RELATED FUNCTIONS: 


ferror, fopen, fputc, fwrite, getc, printf, putc, 
putchar, puts. 
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rand 
Generate random numbers. 
SYNTAX: 
int rand() 
ARGUMENTS; 
None. 
DESCRIPTION: 


The rand function uses a epee yeaheah congruential random 
number generator with period 232 to return successive 
pseudorandom numbers in the range from 0 to 2i5 -1, 

RELATED FUNCTIONS: 


srand, 
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read 

Reads from a file. 

SYNTAX: 
int read (fildes, buf, nchar) 
int fildes; 
char *buf; 
unsigned nchar; 

ARGUMENTS : 

fildes 


File descriptor obtained from a creat, open, dup, fcntl, 
Or pipe function call. 


buf 
Pointer to buffer. 
nchar 
Number of characters to read. 
DESCRIPTION: 
The read function attempts to read nchar characters from the 
file associated with fildes into the buffer pointed to by 


buf. 


Text file end-of-file processing is compatible with a UNIX 
operating system. 


The read function does not allocate a buffer until it is 
needed. 


RETURN VALUE: 

Upon successful completion, a nonnegative integer is returned 
indicating the number of characters actually read and placed 
in the buffer. A value of -1 is returned when an end of file 
has been reached. A -1l is returned and the variable errno is 
set to indicate the error... 

RELATED FUNCTIONS: 


creat, fcntl, open. 
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realloc 

Reallocates heap memory. 
SYNTAX: 

char *realloc (ptr, size) 

char *ptr; 

unassigned size; 
ARGUMENTS : 
ptr 

Pointer to memory area to be reallocated. 
size 

New size, in characters. 
DESCRIPTION: 
The realloc function allocates an area of size and copies the 
value of the previous block into the new block for the 
specified size. 
DIAGNOSTICS: 
If the heap does not contain enough memory, and cannot be 
sufficiently expanded to meet the request, the variable errno 
is set to ENOMEN at ENOSPC and a null character pointer is 
returned. When realloc returns a null pointer, the block 
pointed to by ptr may have been destroyed. 
RELATED FUNCTIONS: 


calloc, free, malloc. 
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sbrk 


Changes data segment space allocation. 
SYNTAX 


char *sbrk (incr) 
int incr; 


ARGUMENTS : 
incr 

Number of characters to add to brk value. 
DESCRIPTION: 


sbrk has been converted to operate in the same 
malloc. 


4-165 


sbrk 
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scanf 
Formatted input conversion. 
SYNTAX: 
# include <stdio.h> 


scanf (format [,pointer]...) 
char *format; 


ARGUMENTS : 
format 

Control string format. 
pointer 


Set of arguments indicating where the converted input 
should be stored. 


DESCRIPTION: 

The scanf function reads from the standard input file stdin. 
This function reads characters, interprets them according to 
a format, and stores the results in its arguments. It 
requires a control string format and a set of optional 
pointer arguments indicating where the converted input should 
be stored. 


The scanf function is equivalent to a call to fscanf with the 
argument stdout inserted before the arguments to scanf. 


For more information on this function, refer to the 
description of the fscanf function. 


RELATED FUNCTIONS: 


atof, fscanf, getc, printf, sscanf. 
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setbuf 
Assign buffering to a file. 
SYNTAX: 
# include <stdio.h> 
setbuf (file, buf) 
FILE *file; 
char *buf; 
ARGUMENTS ¢ | 
file 
File pathname. 
buf 
Pointer to buffer address. 
DESCRIPTION: 
The setbuf function is used after a file has been opened but 
before it is read or written. It causes the character array 
buf to be used instead of an automatically allocated buffer. 
A manifest constant BUFSIZ tells how big an array is needed: 
char buf[BUFSIZ]; 
RELATED FUNCTIONS: 


fopen, getc, putc. 
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setjmp 
Non-local goto. 
SYNTAX: 
# include <setjmp.h> 


int setjmp (env) 
jmp_buf env; 


ARGUMENTS : 
env 

Pointer to a label structure for later use by longjmp. 
DESCRIPTION: 


The setjmp function saves a label structure in env for later 
use by longjmp. 


This routine is useful for dealing with errors and interrupts 
encountered in a low-level subroutine of a program. 


RETURN VALUE: 
This function returns the value zero. 
RELATED FUNCTIONS: 


kill, longjmp, signal. 
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Signal 
Specifies what to do upon receipt of a signal. 
SYNTAX: 
# include <signal.h> 
int (*signal (sig, func))() 
int sig; 
int (*func)(); 
ARGUMENTS : | 
Sig 
Signal to be processed. 
func 
SIG_DFL, SIG_IGN, or a function address (see below). 
DESCRIPTION: 


The signal function allows the calling process to choose one 
of three ways to handle the receipt of a specific signal. 
The sig argument specifies the signal and the func argument 
specifies the choice. 


A Signal is generated by some abnormal event, such as a 
Megabus error, receipt of a kill, or your pressing Break. 
Normally, all signals terminate the process. The signal 
function allows a process to ignore a signal or cause an 
interrupt to a specified location. 


The sig argument can be assigned from the following: 


SIGHUP 01 Hangup 

SIGINT 02 Interrupt 

SIGQUIT 03* Quit 

SIGILL 04* Invalid instruction 

SIGTRAP 05% Trace trap (not reset when caught) 
SIGIOT 06* IOT instruction 

SIGEMT 07* EMT instruction 

SEGFPE 08* Floating-point exception 

SIGKILL 09 Kill (cannot be caught or ignored) 
SIGBUS 10* Megabus error 

SIGSEGV 11* Segmentation violation 

SIGSYS 12* Invalid argument to function 
SIGALRM 14 Alarm clock 
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SIGTERM is Software termination signal 
SIGUSR1 16 User-defined signal 1 

SIGUSR2 17 User-defined signal 2 

SIGCLD 18 Death of a child (see note) 
SIGPWR 19 Power failure recovery (not reset 


when caught) 
The actions prescribed by the sig argument are: 


e SIG_DFL -- Pass the signal to the default_error 


handler (refer to Multics Programmer's Reference 
Manual). 


e SIG_IGN -- The signal sig is to be ignored; the 
setting of func remains as SIG_IGN. 


e function address -- Upon receipt of the signal sig, 
the receiving process is to execute the signal- 
catching function pointed to by func. 


Upon return from the signal-catching function, the 
receiving process resumes from the point where it was 
when the Signal was caught. The value of func for a 
caught signal is reset to SIG_DFL unless the catching 
function executes a call to the signal function to set 
it otherwise. 


RETURN VALUE: 


Upon successful completion, signal returns the nrevious value 
of func for the specified signal sig. Otherwise, a value of 
-l is returned and the variable errno is set to indicate the 
error. 


DIAGNOSTICS: 
The signal function fails if: 


@ The argument sig is an illegal signal number, 
including SIGKILL [EINVAL]. 


If a signal catcher is invoked while a process is executing a 
heap management function, and that signal catcher causes a 
recurSive invocation of a heap management function by calling 
(even indirectly) any heap management function, the heap can 
be left in an inconsistent state. The heap can also be left 
in an inconsistent state if such a signal catcher abandons 
the heap management function uSing a nonlocal goto. The 
default signal catcher does neither of these things. (For 
the purpose of this note, the heap management functions are 
calloc, malloc, and free.) 
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RELATED FUNCTIONS: 


kill, setjmp. 
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Sine function. 
SYNTAX: 
# include <math.h> 


double sin (x) 
double x; 


ARGUMENTS: 
x 

Double-precision value. 
DESCRIPTION: 
The sin function returns the sine of a radian argument. The 
magnitude of the argument should be checked by the caller to 
make sure the result is meaningful. 


RELATED FUNCTIONS: 


acos, aSin, atan, atan2, cos, tan. 
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sinh 
Hyperbolic sine function. 
SYNTAX 
# include <math.h>. 


double sinh (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value. 
DESCRIPTION: 


The sinh function computes the hyperbolic sine function for 
real arguments. 


DIAGNOSTICS: 


The sinh function returns a huge value of appropriate sign 
when the correct value would overflow. 


RELATED FUNCTIONS: 


cosh, tanh. 
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sleep 


Suspend execution for interval. 
SYNTAX: 


unsigned sleep (seconds) 
unsigned seconds; 


ARGUMENTS: 
seconds 

Number of seconds to suspend execution. 
DESCRIPTION; 


The sleep function suspends the current process from 
execution for a specified number of seconds. The actual 
suspension time may be less than that requested for two 
reasons: because scheduled wakeups occur at fixed 1-second 
intervals, and because any caught Signal terminates the sleep 
following execution of that signal's catching routine. Also, 
the suspension time may be longer than requested by an. 
arbitrary amount due to the scheduling of other activity in 
the system. The value returned by sleep is the "unslept" 
amount (the requested time minus the time actually slept) in 
case the caller had an alarm set to go off earlier than the 
end of the requested sleep time, or premature arousal due to 
a caught signal. 


The routine is implemented by setting an alarm Signal. The 
previous state of the alarm signal is saved and restored. The 
calling program may have set up an alarm signal before 
calling sleep. If the sleep time exceeds the time until such 
an alarm signal, the process sleeps only until the alarm 
Signal would have occurred, and the caller's alarm catch 
routine is executed just before the sleep routine returns. 

If the sleep time is less than the time until such an alarm, 
the prior alarm time is reset to go off at the same time it 
would have without the intervening sleep. 


RELATED FUNCTIONS: 


alarm, signal. 
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sprintf 


Formats output. 
SYNTAX: 
# include <stdio.h> 


int sprintf (s, format [, arg] ... ) 
char *s, format; 


ARGUMENTS : 
format 

Format string. 
arg 


Optional argument to be printed. . 


Address of location to begin output. 
DESCRIPTION: 
The sprintf function places "output," followed by the null 
character (\0) in consecutive characters starting at *s; you 
must ensure that enough storage is available. 
This function is equivalent to a call to fprintf, except that 
the argument s specifies an array into which the generated 
output is written instead of a file. 


For more information on this function, refer to the 
description of printf. 


RELATED FUNCTIONS: 


ecvt, fprintf, printf, putc, scanf. 
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sqrt 


Square root function. 
SYNTAX 
# include <math.h> 


double sqrt (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value. 
DESCRIPTION: 


The sqrt function returns the square root of x. X cannot be 
negative. 


DIAGNOSTICS: 


The sqrt function returns zero and sets errno to EDOM when x 
is negative. 


RELATED FUNCTIONS: 


exp, hypot, log, pow, sinh. 
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srand 
Reset random number generator. 
SYNTAX 3 


srand (seed) 
unsigned seed; 


ARGUMENTS : 
seed 
Seed value. 
DESCRIPTION: 
The srand function reinitializes the random number generator 
function. It can be set to a random starting point by 
- calling srand with any argument. 


RELATED FUNCTIONS: 


rand. 
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sscanf 
Formatted input conversion. 
SYNTAX: 
# include <stdio.h> 


sscanf (s, format [,pointer]...) 
char *s, *format; 


ARGUMENTS : 
s 

Input character string. 
format 

Control string format. 
pointer 


Set of arguments indicating where the converted input 
should be stored. 


DESCRIPTION: 

The sscanf function reads from the character string s. This 
function reads characters, interprets them according to a 
format, and stores the results in its arguments. It requires 
a control string format and a set of optional pointer argu- 
ments indicating where the converted input should be stored. 
The sscanf function is equivalent to a cali to fscanf, except 
that the argument s specifies an array from which input is 
obtained rather than a file. 


For more information on this function, refer to the 
description of fscanf. 


RELATED FUNCTIONS: 


atof, fscanf, getc, printf, scanf. 
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Get file status. 


SYNTAX: 


# inciude <types.h> 
# include <stat.h> 


int stat (path, buf) 


char *path; 
struct stat *buf; 


ARGUMENTS : 


path 


File pathname. 


stat 


Read, write, or execute access to the 


named file is not required, but all directories listed in 
the pathname leading to the file must be searchable. 


buf 


Pointer to a static structure into which information is 
placed concerning the file. 


DESCRIPTION: 


The stat function obtains information about the named file. 


The contents of the structure pointed to by buf include the 
following members: 


ushort 
ino_t 
dev_t 


dev_t 


short 
ushort 
ushort 
off t 
time_t 
time_t 


time_t 


st_mode; 
st_ino; 
st_dev; 


st_rdev; 


st_nlink; 
st_uid; 
Sst_gid; 
st_size; 
st_atime; 
st_mtime; 


st_ctime; 


/*File mode */ 
/*Inode number (N/A in MOD 400) */ 
/*ID of device containing */ 
/*a directory entry for this file */ 
/*ID of device */ 


/*This entry is defined only for */ 

/*character special or block special 
files * 

/*Number of links (N/A in MOD 400) */ 


/*User ID of the file's owner */ 
/*Group ID of the file's group */ 
/*File size in characters (N/A) */ 
/*Time of last access */ 


/*Time of last data modification */ 

/*Time measured in seconds since 
00:00:00 GMT, Jan. 1, 1970 */ 

/*Time of creation x7 
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Stat 
The st_atime member is the date/time when the file was last 
accessed. It is changed by the functions creat and read. 


The st_mtime member is the date/time when the file was last 
modified. It is changed by the functions creat and vrite. 


The st_ctime member is the date/time when the file was 
created. It is changed by the following functions: creat, 
link, unlink, and write. 


Information is not available in the members st ino, st_nlink, 
and st_size. 


RETURN VALUE: 

Upon successful completion a value of 0 is returned. 
Otherwise, a value of -1l is returned and errno is set to 
indicate the error. 

DIAGNOSTICS: 


The stat function fails if: 


@e A component of the path prefix is not a directory 
[ENOTDIR]. 


e The named file does not exist [ENOENT]. 


e Search access is denied for a component of the path 
prefix [EACCES]. 


RELATED FUNCTIONS: 


creat, fstat, link, stat, time, unlink. 
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strcat 
Concatenates strings. 
SYNTAX: 


char *strcat (sj), S92) 
char *sj, *sS2; 


ARGUMENTS : 
Sl, S2 
Null-terminated strings. 
DESCRIPTION: 
The strcat function appends a copy of string s2 to the end of 
string sj. It returns a pointer to the null-terminated 
result. This function does not check for overflow of any 
receiving string. 
NOTE 
All string movement is performed character by 
character, starting at the left. Thus, over- 


lapping moves toward the left work as expected, 
but overlapping moves to the right may not. 


RELATED FUNCTIONS: 


strchr, strcmp, strcpy, strcspn, strlen, strncat, 
strncmp, strncpy, strpbrk, strrchr, strspn, strtok. 
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strchr 
Finds character in string. 
SYNTAX: 


char *strchr (s, c) 
char *s, Cc; 


ARGUMENTS : 
Ss 


String to search. 


Character to seek. 
DESCRIPTION: 
The strchr function returns a pointer to the first occurrence 
of character c in string s, or NULL if c does not occur in 


the string. The null character terminating a string is 
considered to be part of the string. 


The strchr function operates on null-terminated strings. 
This function does not check for overflow of any receiving 
string. 

RELATED FUNCTIONS: 


strcat, strcmp, strcpy, strcspn, strlen, strncat, 
strncmp, strncpy, strpbrk, strrchr, strspn, strtok. 
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strcmp 
Compares strings. 
SYNTAX: 


int strcmp (s], S92) 
char *sj, *S9; 


ARGUMENTS: 
S11, $2 

Null-terminated strings. 
DESCRIPTION: 
The strcmp function compares itS arguments and returns an 
integer greater than, equal to, or less than zero, according 
to whether s} is lexicographically greater than, equal to, or 
less than s2. This function does not check for overflow of 
any receiving string. 


RELATED FUNCTIONS: 


strceat, strchr, strcpy, strcspn, strlen, strncat, 
Strncmp, strncpy, strpbrk, strrchr, strspn, strtok. 
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strcpy 
Copies string. 
SYNTAX: 


char *strcpy (sj, $2) 
char :*S8)4.°*S9? 


ARGUMENTS : 
S1, S82 

Null-terminated strings. 
DESCRIPTION: 


The strcpy function copies string sz to sj, stopping after 
the null character has been moved. It returns sj. This 
function does not check for overflow of any receiving string. 


NOTE 
All string movement is performed character by 
character, starting at the left. Thus, over- 


lapping moves toward the left work as expected, 
but over- lapping moves to the right may not. 


RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcspn, strlen, strncat, 
strncmp, strncpy, strpbrk, strrchr, strspn, strtok. 


strespn 


strcspn 
Substring operation. 
SYNTAX: 


int strcspn (sj, 82) 
char *sj, *s?2 


ARGUMENTS : 
Sl, 82 

Null-terminated strings. 
DESCRIPTION: 
The strcspn function returns the length of the initial 
segment of string s} which consists entirely of characters 
not from string sz. This function does not check for 
overflow of any receiving string. 


RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcpy, strlen, strncat, strncmp, 
strncpy, strpbrk, strrchr, strspn, strtok. 
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Strlen 
Finds length of string. 
SYNTAX 


int strlen (s) 
char *s; 


ARGUMENTS : 
Ss 
Null-terminated string. 
DESCRIPTION: 
The strlen function returns the number of non-null character 
in s. This function does not check for overflow of any 
receiving string. 
RELATED FUNCTIONS: 


Strcat, strchr, strcmp, strcpy, strcspn, strncat, 
strncemp, strncpy, strpbrk, strrchr, strspn, strtok. 


4-186 HH07-01 


strncat 


strncat 
Concatenates portion of string. 
SYNTAX: 
char *strncat (sj, s3, n) 
char -*S7.,. *S9; 
int n; 
ARGUMENTS : 
S1, 82 
Null-terminated strings. 
DESCRIPTION: 
The strcat function appends at most n characters of string s? 
to the end of string sj}. It returns a pointer to the 
null-terminated result. This function does not check for 
overflow of any receiving string. 
NOTE 
All string movement is performed character by 
character, starting at the left. Thus, over- 
lapping moves toward the left work as expected, 
but over- lapping moves to the right may not. 
RELATED FUNCTIONS: 


Sstrcat, strchr, strcmp, strcpy, strcspn, strlen, strncmp, 
strncpy, strpbrk, strrchr, strspn, strtok. 
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strncmp 

Compares to portion of String. 

SYNTAX: 
int strncmp (sj, S2, n) 
char *sj, *S92; 
int n; 

ARGUMENTS : 

Sl, $2 


Null-terminated strings. 


Number of characters to check. 
DESCRIPTION: 


The strncmp function looks at up to n characters of string sj 
and compares it to argument sj, and returns an integer . 
greater than, equal to, or less than zero, according to 
whether s) 1s lexicographically greater than, equal to, or 
less than s32. This function does not check for overflow of 
any receiving string. 


RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, 
strncpy, strpbrk, strrchr, strspn, strtok. 


strncpy 


strncpy 

Copies n characters. 

SYNTAX: 
char *strncpy (sj, s2, n) 
char *s}, *s3; 
int n; 

ARGUMENTS : 

Sl, $2 


Null-terminated strings. 


Number of characters to copy. 
DESCRIPTION: 


The strncpy function copies exactly n characters of string s2 
to Sj], truncating or null-padding s2; the target might not be 
null-terminated if the length of sz 1S n or more. It returns 
S,}- This function does not check for overflow of any 
receiving string. 


NOTE 
All. string movement is performed character by 
character, starting at the left. Thus, over- 


lapping moves toward the left work as expected, 
but overlapping moves to the right may not. 


RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, 
strncemp, strpbrk, strrchr, strspn, strtok. 
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strpbrk 


Locates substring. 
SYNTAX: 


char *strpbrk (sj, s2) 
char *sj, *sS92; 


ARGUMENTS : 
S1, 82 

Null-terminated strings. 
DESCRIPTION: 
The strpbrk function returns a pointer to the first 
occurrence in string sj of any character from string s92, or 
NULL if no character from sz existS in Ss}. This function 
does not check for overflow of any receiving string. 


RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, 
strncmp, strncpy, strrchr, strspn, strtok. 
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strrchr 
Finds last occurrence of substring. 
SYNTAX $ 


char *strrchr (s, c) 
char *s, c}3 


ARGUMENTS : 
Ss 


Null-terminated string. 


Character to check for. 
DESCRIPTION: 
The strrchr function returns a pointer to the last occurrence 
of character c in string s, or NULL if c does not occur in 
the string. The null character terminating a string is 
considered to be part of the string. This function does not 
check for overflow of any receiving string. 
RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, 
strncemp, strncpy, strpbrk, strspn, strtok. 
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strspn 
Gets length of substring. 
SYNTAX: 


int strspn (sj, $2) 
Char *sj, *S?2; 


ARGUMENTS : 
Sl], 82 

Null-terminated strings. 
DESCRIPTION: 
The strspn function returns the length of the initial segment 
of string sj, which consists entirely of characters from 
string s2. This function does not check for overflow of any 
receiving String. 
RELATED FUNCTIONS: 


Strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, 
strncemp, strncpy, strpbrk, strrchr, strtok. 
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strtod 
Convert string to double-precision number. 
SYNTAX: 


double strtod (str, ptr) 
char *str, **ptr; 


ARGUMENTS : 
str 

A pointer to a null-terminated string. 
ptr 

A pointer to the return value. 
DESCRIPTION: 
strtod returns as a double-precision floating-point number 
the value represented by the character string pointed to by 
str. The string is scanned up to the first unrecognized 
character. 
strtod recognizes an optional string of "white-space" 
characters (as defined by isspace in ctype), then an optional 
Sign, then a string of digits optionally containing a decimal 
point, then an optional e or E followed by an optional sign 
or space, followed by an integer. 
if the value of ptr is not NULL, a pointer to the character 
terminating the scan is returned in the location pointed to 


by ptr. If no number can be formed, *ptr is set to str, and 
zero is returned. 
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strtok 
String token operation. 
SYNTAX: 


char *strtok (sj, s2) 
char *s), *S2; 


ARGUMENTS : 


Sl, 82 
Null-terminated strings. 
DESCRIPTION: 


The strtok function considers the string sj to consist of a 
sequence of zero or more text tokens separated by spans of 
one or more characters from the separator string s3. The 
first call (with pointer s ; specified) returns a pointer to 
the first character of the first token, and will have written 
a NULL character into sj immediately following the returned 
token. Subsequent calls with zero for the first argument 
work through the string sj in this way until no tokens 
remain. The separator string s2 may be different from call 
to call. When no token remains in sj, a NULL is returned. 
This function does not check for overflow of any receiving 
string. 


NOTE 
All string movement is performed character by 
character, starting at the left. Thus, over- 
lapping moves toward the left work as expected, 
but overlapping moves to the right may not. 


RELATED FUNCTIONS: 


strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat,: 
strncmp, strncpy, strpbrk, strrchr, strspn. 
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strtol 

Convert string to integer. 
SYNTAX: 

long strtol (str, prt, base) 

char *str **ptr; 

int base; 
ARGUMENTS : 
str 

A pointer to a character string. 
ptr 

A pointer to a return value. 
base 

Specifies the conversion base. 
DESCRIPTION: 
strtol returns as a long integer the value represented by the 
character string pointed to by str. The string is scanned up 
to the first character inconsistent with the base. Leading 
"white-space" characters (as defined by isspace in ctype) are 
ignored. 
If the value of ptr is not NULL, a pointer to the character 
terminating the scan is returned in the location pointed to 
by ptr. If no integer can be formed, that location is set to 
str, and zero is returned. 
If base is positive (and not greater than 36), it is used as 
the base for conversion. After an optional leading sign, 
leading zeros are ignored, and "Ox" or "OX" is ignored if 
base is 16. 
If base is zero, the string itself determines the base 
thusly: after an optional leading sign a leading zero 
indicates octal conversion, and a leading "Ox" or "OX" 
hexadecimal conversion. Otherwise, decimal conversion is 
used. 


Truncation from long to int can, of course, take place upon 
assignment or by an explicit cast. 
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Swap bytes. 
SYNTAX: 
swab (fr, to, nbytes) 
char *fr, *to:; 
int nbytes; 
ARGUMENTS: 
fr 


Pointer to memory area from which bytes are taken. 


to 

Pointer to memory area in which bytes are placed. 
nbytes 

Number of bytes to move; argument should be an even 

number. 
DESCRIPTION: 


The swab function copies nbytes bytes pointed to by fr to the 
position specified by to, exchanging adjacent even and odd 
bytes. 


This function is useful on machines where strings of 
characters are stored from right to left within words and 
from left to right from word to word, and where words are two 
characters wide. 
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system 


Issues a Multics command. 
SYNTAX: 
# include <stdic.h> 


int system (string) 
char *string; 


ARGUMENTS : 
string 

Command line. 
DESCRIPTION: 
The system function causes the string to be given to Multics 
as input as if the string had been typed as a command at a 
terminal. The current process waits until the command has 


completed, then returns the exit status of the command. 


DIAGNOSTICS: 


An exit status return of -l is returned if the command 
processor could not be called successfully. 
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sys_errlist 
System error messages. 
SYNTAX 

char *sys_errlist []; 

ARGUMENTS : 
None. 
DESCRIPTION: 
To simplify variant formatting of error messages, the vector 
of message strings sys_errlist is provided; the variable 
errno can be used as an index in this table to get the 
message string without the newline character. The variable 
sys_nerr is the largest message number provided for in the 
table; it should be checked because new error codes may be 
added to the system before they are added to the table. 
RELATED FUNCTIONS: 


errno, perror, sys_nerr. 


syS__nerr 


sys_nerr 
Number of largest system error message. 
SYNTAX 3 


int syS_nerr; 
char *sys_errlist []; 


ARGUMENTS : 

None. 

DESCRIPTION: 

To simplify variant formatting of messages, the vector of 
message Strings sys _errlist is provided; the variable errno 
can be used as an index in this table to get the message 
string without the newline character. The variable sys_nerr 
is the largest message number provided for in the table; it 
should be checked because new error codes may be added to the 
system before they are added to the table. 

RELATED FUNCTIONS: 


errno, perror, sysS_errlist. 
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Tangent function. 
SYNTAX: 
# include <math.h> 


double tan (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value. 
DESCRIPTION: 
The tan function returns the tangent of a radian argument. 
The caller should check the magnitude of the argument to make 
Sure the result is meaningful. 


RELATED FUNCTIONS: 


acos, aSin, atan, atan2, cos, sin. 
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tanh 
Hyperbolic tangent function. 
SYNTAX: 
# include <math.h> 


double tanh (x) 
double x; 


ARGUMENTS : 
x 

Double-precision value. 
DESCRIPTION: 


The tanh function computes the hyperbolic tangent function 
for real arguments. . 


RELATED FUNCTIONS: 


cosh, sinh. 
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time 
Gets time. 
SYNTAX: 


long time ((long *) 0) 


long time (tloc) 
long *tloc; 


ARGUMENTS : 
tloc 

Pointer to memory area in which result is returned. 
DESCRIPTION: 


The time function returns the value of time in seconds since 
00:00:00 GMT, January 1, 1970. 


If tloc is not null, the return value is also stored in the 
location to which tloc points. 3 


RETURN VALUE: 

Upon successful completion, time returns the value of time. 
Otherwise, a value of -1 is returned, and the variable errno 
is set to indicate the error. 


DIAGNOSTICS: 


The time function fails if tloc points to an invalid address 
[EFAULT]. | 
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times 
Get process and child process times. 
SYNTAX: 


#include <sys/types.h> 
#include <sys/times.h> 


long times (buffer) 
struct tms *buffer; 


ARGUMENTS : 
buffer 
A pointer to a tms structure (see below). 
DESCRIPTION: 
Times fills the structure pointed to by buffer with 
time-accounting information. The following are the contents 
of this structure: 
struct tms { 
time_t tms_utime; 
time_t tms_stime; 
time_t tms_cutime; 
time_t tms_cstime; 
}; 
This information comes from the calling process and each of 
its terminated child processes for which it has executed a 
wait. 


tms_utime is the CPU time used while executing instructions 
in the user space of the calling process. 


tms_stime is the CPU time used by the system on behalf of the 
calling process. Will be zero. 3 


tms_cutime is the sum of the tms_utimes and tms_cutimes of 
the child processes. Will be zero. 


NOTE 
tms_cstime is unavailable on Multics. 


times will fail if buffer points to an illegal address 
[EFAULT]. 
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RETURN VALUE: 


Upon successful completion, times returns the elapsed real 
time, in 60ths (100ths) of a second, since an arbitrary point 
in the past (e.g., system start-up time). This point does 
not change from one invocation of times to another. If times 


fails, a -l1 is returned and errno is set to indicate the 
error. 


tmpnam 


tmpnam 
Creates a name for a temporary file. 
SYNTAX: 
# include <stdio.h> 


char *tmpnam (s) 
char *s;. 


ARGUMENTS : 
s 

Address of array to receive result. 
DESCRIPTION: 


The tmpnam function generates a file name that can safely be 
used for a temporary file. If (int)s is zero, tmpnam leaves 
its result in an internal static area and returns a pointer 
to that area. The next call to tmpnam destroys the contents 
of the area. If (int)s is nonzero, s is assumed to be the 
address of an array of at least L_tmpnam characters, where 
L_tmpnam is a constant defined in stdio.h; tmpnam places its 
result in that array and returns s as its value. 


The tmpnam function generates a different file name each time 
it is called. 


Files created using tmpnam and either fopen or creat are only 
temporary in the sense that they reside in a directory 
intended for temporary use, and their names are unique. You 
must use unlink to remove the file when its use is ended. 
RELATED FUNCTIONS: 


create, unlink, fopen, mktemp. 
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toascii 
Character translation. 
SYNTAX: 
# include <ctype.h> 


int toascii (c) 
int c; 


ARGUMENTS : 
c 

Character to translate. 
DESCRIPTION: 
The toascii function translates a character into 7-bit ASCII. 
The toascii function yields its argument with all bits turned 
off that are not part of a standard 7-bit ASCII character; it 
is intended for compatibility with other systems. 


RELATED FUNCTIONS: 


ctype, getc, tolower, toupper. 


tolower 


tolower 
Character translation. 
SYNTAX: 
# include <ctype.h> 


int tolower (c) 
int c; 


ARGUMENTS : 
Cc 

Character to translate. 
DESCRIPTION: 
The tolower function has as a domain all 8-bit ASCII codes 
(hexadecimal 0 through FF). If the argument represents an 
uppercase letter, the result is the corresponding lowercase 
letter. All other arguments in the domain are returned 
unchanged. 


RELATED FUNCTIONS: 


ctype, getc, toascii, toupper. 
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_tolower 


Character translation. 
SYNTAX: 
# include <ctype.h> 


int _tolower (c) 
int Cc; 


ARGUMENTS: 
es 

Character to translate. 
DESCRIPTION: 
The _tolower macrocall takes as an argument an uppercase 
letter. The result is the corresponding lowercase letter. 
All other arguments cause unspecified results. 


RELATED FUNCTIONS: 


ctype, getc, toascii, toupper. 


toupper 


toupper 


Character translation. 
SYNTAX: 
# include <ctype.h> 


int toupper (c) 
int ‘¢; 


ARGUMENTS : 
Cc 

Character to translate. 
DESCRIPTION: 
The toupper function has as a domain all 8-bit ASCII codes 
(hexadecimal 0 through FF). If the argument represents a 
lowercase letter that has a corresponding uppercase letter, 
the result is that uppercase letter. All other arguments in 
the domain are returned unchanged. 


RELATED FUNCTIONS: 


ctype, getc, toascii, tolower. 
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_toupper 


Character translation. 
SYNTAX: 
# include <ctype.h> 


int _toupper (c) 
int c; 


ARGUMENTS : 
Cc 

Character to translate. 
DESCRIPTION: 
The _toupper macrocall takes as an argument a lowercase 
letter that has a corrseponding uppercase letter. The result 
is the corresponding uppercase letter. All other arguments 
in the domain cause unspecified results. 


RELATED FUNCTIONS: 


ctype, getc, toascii, tolower. 
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tzset 
Set time zone. 
SYNTAX: 
void tzset () 
DESCRIPTION: 
The tzset function sets the external variables timezone, 
daylight, and tzname, using either the external variable TZ 
(if present) or the system time zone. It is called by the 


asctime function, but you can also call it directly. 


The value of TZ must be a time zone acronym, a time offset, 
and an optional daylight-savings time zone acronym. 


@® The time zone acronym is up to four characters long. 

@ The time offset represents the difference between 
local time in the designated time zone and GMT. The 
difference is represented by a string of digits with 
an optional leading minus sign (for locations east of 
Greenwich, England) and with an optional trailing .5 
(for locations some odd number of half-hours from 
Greenwich). 


e The optional daylight savings time zone acronym is up 
to four characters long. 


For example, the setting for Boston would be EST5EDT. 
RELATED FUNCTIONS: 


asctime, ctime, gmtime, localtime, time. 
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ulimit 
Get and set user limits. 
SYNTAX: 
long ulimit (ena: newlimit) 
int cmd; 
long newlimit; 
ARGUMENTS : 
cmd 
The command to execute. The cmd values available are: 


1 -- Get the file size limit of the process. 


2 -- (On Multics the maximum segment size is set by 
system defaults). 


3 -- Get the maximum possible allocation size. 
newlimit 
The new size. 
DESCRIPTION: 
This function provides for control over process limits. 
RETURN VALUE: 
Upon successful completion, a non-negative value is 


returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 
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ungetc 
Pushes character back into input file. 
SYNTAX: 
int ungetc (c, file) 
char c; 
FILE *file; 
ARGUMENTS : 
Cc 
Character to push. 
file @ 
Pathname of input file. 
DESCRIPTION: 
The ungetc function pushes the character c back on an input 
file. That character is returned by the next getc call on 
that file. The ungetc function returns c. 
One character of pushback is guaranteed provided something 
has been read from the file and the file is actually 
buffered. Attempts to push EOF are rejected. 
DIAGNOSTICS: 


The ungetc function returns EOF if it cannot push a character 
back. 


RELATED FUNCTIONS: 


getc, setbuf. 
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unlink 
Removes directory entry. 
SYNTAX: 


int unlink (path) 
char *path; 


ARGUMENTS : 
path 

Pathname of directory entry. 
DESCRIPTION: 
The unlink function deletes the file entry named by the path 
argument. If path is a link, the link is removed. If path 
is a file, the file is deleted. 
RETURN VALUE: 
Upon successful completion, a value of 0 is returned. 
Otherwise, a value of -1l is returned and the variable errno 
is set to indicate the error. 
DIAGNOSTICS: 
The unlink function fails if: 

e The volume is write protected [EROFS]. 
RELATED FUNCTIONS: 


close, link, open. 
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utime 
Set file access and modification times. 
SYNTAX: 
#include <sys/types.h> 
int utime (path, times) 
char *path; 
struct utimbuf *times; 
ARGUMENTS ; 
path 


Path points to a path name naming a file. utime sets the 
access and modification times of the named file. 


times 


On Multics utime can only change the access times to the 
current time. 


DESCRIPTION: 


The times in the following structure are measured in seconds 
since 00:00:00 GMT, Jan. 1, 1970. 


struct utimbuf { 
time_t actime; /* access time */ 
time_t modtime; /* modification time */ 


}; 
utime will fail if one or more of the following are true: 
e The named file does not exist [ENOENT]. 


@ A component of the path prefix is not a directory 
[ENOTDIR]. 


e Search permission is denied by a component of the path 
prefix [EACCES]. | 


RETURN VALUE: 
Upon successful completion, a value of 0 is returned. 


Otherwise, a value of -l is returned and errno is set to 
indicate the error. 
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varargs 


Handle variable argument list. 
SYNTAX: 
#include ejatavgech= 
va_alist 
va_dcl 


va_list get_arg(), last_arg(); 
va_list pvar; 


pvar = get_arg; 


void va_start(pvar) 
va_list pvar; 


type va_arg(pvar, type) 
va_list pvar; 


void va_end(pvar) 
va list pvar; 


DESCRIPTION: 


This set of macros allows portable procedures that accept 
variable argument lists to be written. Routines that have 
variable argument lists (such as printf) but do not use 
varargs are inherently nonportable, as different machines use 
different argument-passing conventions. 


va_alist is used as the parameter list in a function header. 


va_dcl is a declaration for va_alist. No semicolon should 
follow va_dcl. 


va_list is a type defined for the variable used to traverse 
the list. 


get_arg is a routine that returns a va_list pointer to the 
required argument. Due to the argument list structure on 
Multics a direct relationship between an arguments address 
and itS position in the argument list does not exist. 

get_arg is used to return the required va_list pointer to the 
argument. In the call pvar = get_arg; get_arg will return a 
va_list pointer to the third argument in the routines 
argument list. 
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last_arg returns a va_list pointer to the last argument being 
passed. This will usually be the return argument. last_arg 
is used by va_end to test for the last argument. 


va_Start is called to initialize pvar to the beginning of the 
list. If the argument is the first argument then va_start 
can be used to get a va_list pointer to the first argument. 
If an argument in another position is required as the 
Starting position then get_arg must be used. 


va_arg will return the next argument int he list pointed to 
by pvar. Type is the type the argument is expected to be. 
Different types can be mixed, but it is up to the routine to 


know what type of argument is expected, as it cannot be 
determined at runtime. 


va_end is used to clean up. 


Multiple traversals, each bracketed by va_start or get_arg 
-.. vVa_end, are possible. 


The following example is a possible implementation of execl: 


#include <varargs.h> 


#define MAXARGS 100 
7* execl is called by 
execl(file, argl, arg2, ..., (char *)0); 
/* 
execl(va_alist) 
va_dcel 


va_list ap; 

‘char *file; 

char *args[MAXARGS]; 

int argno = 0; 

va_start(ap); 

file = *va_arg(ap, char *); 

while ((args[argno++] = *va_arg(ap, char *)) != (char *)0) 


tf 
va_end(ap; 
return execv(file, args); 
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or execl could be done as follows using get_arg: 


#include <varargs.h> 
#define MAXARGS 100 


/* execl is called by te 
execl (file, argl, arg2, .... NULL); 
*/ 


execl (file, va_alist) 
char *file; 
va_dcl 


{ 
va_list ap; 
char *args [MAXARGS]; 
int argno = 0; 


ap = get_arg; /* returns a va_list pointer to the 
second argument */ 


while ((args [argno++] = *va_arg (ap, char *)) != NULL) 


fd 
va_end(ap); 
return execv (file,args); 
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vprintf, vfprintf, vsprintf 
Print formatted output of a varargs argument list. 
SYNTAX 3 


#include <stdio.h> 
#include <varargs.h> 


int vprintf (format, ap) 
char *format; 
va_list ap; 
int vfprintf (stream, format, ap) 
FILE *stream; 
char *format; 
va_list ap; 
int vsprintf (s, format, ap) 
char *s, *format; 
va_list ap; 
ARGUMENTS : 
stream 
A file pointer. 
format 


A pointer to a null-terminated string. 


ap 

A pointer to a varying argument list. 
s 

A pointer to the return value. 
DESCRIPTION: 


vprintf, vfprintf, and vsprintf are the same as printf, 
fprintf, and sprintf respectively, except that instead of 
being called with a variable number or arguments, they are 


called with an argument list as defined by varargs. 
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EXAMPLE: 


The following demonstrates how vfprintf could be used to 
write an error routine. 


#include <stdio.h> — 
#include <varargs.h> 


yt 

* error should be called like 

* error (function_name, format, argl, arg2...); 
7 

/*VARARGSO* / 

void 


error(va_alist) 

/* Note that the function_name and format arguments cannot be 
- separately declared because of the definition of varargs. 
* 


va_dcl 


va_list args; 
char *fmt; 


va_start(args); 

/* print out name of function causing error */ 
(void)fprint(stderr, "ERROR in %S ", va_arg(args, char *)); 
fmt = va_arg(args, char *); 

/* print out remainder of message */ 

(void)vfprintf(fmt, args); 

va_end(args); 

(void)abort ( ); 
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write 

Writes ona file. 

SYNTAX: 
int write (fildes, buf, nchars) 
int fildes; 
char *buf; 
unsigned nchars; 

ARGUMENTS : 

fildes 


File descriptor obtained from a creat, dup, open, or pipe 
function. 


buf 

' Address. of buffer containing characters to be written. 
nchars 

Number of characters to write. 

DESCRIPTION: 
The write function attempts to write nchars characters from 
the buffer pointed to by buf to the file associated with the 
file descriptor fildes. 
On devices capable of seeking, the actual writing of data 
proceeds from the position in the file indicated by the file 
pointer. Upon return from write, the file pointer is 
incremented by the number of characters actually written. 
On devices incapable of seeking, writing always takes place 
Starting at the current position. The value of a file 
pointer associated with such a device is unspecified. 


If the O APPEND file status flag is set, the file pointer is 
set to the end of the file before each write. 
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If a write requests that more characters be written than 
there is room for (ULIMIT or the physical end of a medium), 
only as many characters as there is room for will be 

written. For example, if there is space for 20 characters 
more in a file reaching a limit, a write of 512 characters 
returns 20. The next write of a nonzero number of characters 
gives a failure return (except as noted below). 


The write function does not allocate a buffer until it is 
needed. 


RETURN VALUE: 

Upon successful completion, the number of characters actually 
written is returned, Otherwise, -1 is returned and the 
variable errno is set to indicate the error. 


DIAGNOSTICS: 


The write function fails and the file pointer is unchanged 
if: 


e The fildes argument is not a valid file descrapror 
open for writing [EBADF]. 


RELATED FUNCTIONS: 


creat, dup, open, pipe. 
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Appendix A 
C COMPILER 
DIAGNOSTIC MESSAGES | 


This appendix lists the C compiler diagnostic messages .in 
alphabetical order. In messages, [---] indicates a variable. 
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Table A-l lists the C compiler diagnostic messages. These 
messages are written to the error-out file. 


Table A-l1. C Compiler Diagnostic Messages 
(Sheet 1 of 3) 


i[_name] evaluation order undefined Warning 
[name] may be used before set | Warning 
[name] redefinition hides earlier one Error 
[name] set but not used in function [name] Warning 
[name] undefined | Error 
bad structure offset Error 
[name] unused in function [name] Warning 
=<{character] illegal Error 
=>[character] illegal Error 
BCD constant exceeds 6 characters | Error 
a function is declared as an argument Warning 
ambiguous assignment: Simple assign, unary op assumed | Warning 
argument [name] unused in function [name] Warning 
array of functions is illegal Error 
assignment of different structures Error 
bad ASM construction Error 
bad scalar initialization Error 
can't take & of [name] Error 
cannot initialize extern or union Error 
case not in switch Error 
comparison of unsigned with negative constant, Warning 
constant argument to NOT Warning 
constant expected Error 
constant in conditional context Warning 
constant too big for cross-compiler Error 
conversion from long may lose accuracy Warning 
conversion to long may sign-extend incorrectly Warning 
Geclared argument [name] is missing Error 
default not inside switch Error 
degenerate unSigned comparison Warning 
division by 0 Error 
duplicate case in switch [number] | Error 
duplicate default in switch Error 
empty array declaration Warning 
empty character constant Error 
enumeration type clash, operator [operator] Warning 
field outside of structure Error 
field too big Error 
fortran declaration must apply to function Error 
fortran function has wrong type Error 
fortran keyword nonportable Warning 
function [name] has return(e): and return;, Warning 
function declaration in bad content Error 
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Table A-1. C Compiler Diagnostic Messages 
| (Sheet 2 of 3) 


function has illegal storage class 
function illegal in structure or union 
function returns illegal type 


Brror 
Error 
Error 


;gcos BCD constant illegal Error 
illegal array size combination Warning 
illegal break Error 
illegal character: [number] (octal) Error 
illegal class Error 
illegal combination of pointer and integer, op [name] | Warning 
illegal comparison of enums Error 
illegal continue Error 
illegal field size Error 
illegal field type Error 
illegal function Error 
illegal hex constant Error 
illegal indirection Error 
lllegal initialization Error 
illegal lhs of assignment operator Error 
illegal member use: [name] Error 
illegal member use: [name] Warning | 
illegal member use: perhaps [name].[name] Warning 
illegal pointer combination : Warning 
illegal pointer subtraction Error 
illegal register declaration Error 
illegal structure pointer combination Warning 
illegal type combination Error 
illegal type in : | Error 
illegal use of field Error 
illegal zero sized structure member: [name] Warning 
illegal { Error 
loop not entered at top Warning 
member of structure or union required Error 
newline in BCD constant | Error 
newline in string or char constant Error 
no automatic aggregate initializer Error 
non-constant case expression Error 
non-null byte ignored in string initialization Warning 
nonportable character comparison Warning 
nonportable field type Error 
nonunique name demands struct/union or Error 

Struct/union pointer 
null dimenstion Error 
null effect Warning 
old-fashioned assignment operator Warning 
old-fashioned initialization use = Warning 
operands of [operator] have incompatible types, Error 
pointer required Error 
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Table A-2. C Compiler Diagnostic Messages 


(Sheet 3 of 3) 


possible pointer alignment problem Warning 
precedence confusion possible: parenthesize! Warning 
precision lost in assignment to (sign-extended?) Warning 
field 
precision lost in field assignment Warning 
questionable conversion of function pointer Error 
redeclaration of [name] Error 
redeclaration of formal parameter, [name] Error 
pointer casts may be troublesome Warning 
}Size of returns value less than or equal to zero Warning 
statement not reached Warning 
static variable [name] unused Warning 
struct/union [name] never defined Warning 
struct/union or struct/union pointer required Warning 
structure [name] never defined Werror 
Structure reference must be addressable Error 
Structure typed union member must be named Warning 
too many characters in character constant Error 
too many initializers Error 
type clash in conditional Error 
unacceptable operand of & Error 
undeclared initializer name [name] Warning 
undefined structure or union Error 
unexpected EOF Error 
unknown size Error 
unsigned comparison with 0? Warning 
void function [name] cannot return value Error 
void type for [name] Uerror 
void type illegal in expression Error 
zero or negative subscript Warning 
zero size field Error 
zero sized structure Error 
} expected Error 
long in casSe or switch statement may be truncated Warning 
bad octal digit [digit] Warning 
floating point constant folding causes exception Error 
old style assign-op causes syntax error Warning 


main() returns random value to invocation environment | Warning 
‘{name]' may be indistinguishable from '[name]' due Warning 
to internal name truncation 
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Appendix B 
C ENVIRONMENT 
SUPPORT COMMANDS 


The following commands were ported from UNIX System V. _ They’ 


are available to aid in the porting process. 
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touch 


touch 
Update access and modification times of a file. 
SYNTAX: 
touch [ -amc ] files 
DESCRIPTION: 


Touch causes the access and modification times of each 
argument to be updated. The file name is created if it does 
not exist. The current time is used. The -a and -m options 
cause touch to update only the access or modification times 
respectively (default is -am). The -c option silently 
prevents touch from creating the file if it did not 
previously exist. 


The return code from touch is the number of files for which 


the times could not be successfully modified (including files 
that did not exist and were not created). 
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env 


Set environment for command execution. 
SYNTAX 3 

env [ - ] [ name=value ] ... [ command args ] 
DESCRIPTION: 


env obtains the current environment, modifies it according to 
its arguments, then executes the command with the modified 
environment. Arguments of the form name=value are merged 
into the inherited environment before the command is 
executed. The - flag causes the inherited environment to be 
ignored completely, so that the command is executed with 
exactly the environment specified by the arguments. 


If no command is specified, the resulting environment is 
printed, one name-value pair per line. 
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GLOSSARY 


byte 


A Multics byte is nine bits long. In this manual, the terms 
byte and character are synonymous. 


character 

In this manual, the terms character and byte are synonymous. 
character array 

A sequence of characters. 
file 


File names consisting of up to 32 characters are allowed. 
The Multics file naming conventions are listed in the Multics 


Programmer's Reference Manual. 


file access 
File access is controlled in accordance with standard Multics 


conventions as described in the Multics Programmer's 
Reference Manual. 
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file descriptor 


An integer from 0 to 19 that designates a file to be 
processed by low-level 1/0. See low-level I/O. 


heap 
The area in which all memory allocation takes place, 
including all global and C static variables, but not 
including local variables. 


high-level 1/0 


Functions (such as fopen and fprint) that return a pointer to 
a file. See low-level I/0. 


low-level I/0 


Functions (such as close, open, read, and write) that use 
file descriptors. See high-level I/O. 


null character (NUL) 
The ASCII character 00. In C, it is represented as \0. 

null pointer 
The value obtained by casting 0 into a pointer. This value 
never matches any legitimate pointer, so many functions that 
return pointers will return a null pointer to indicate an 
error. 


search rules 


Search rules are described in the Multics Programmer's 
Reference Manual. 


string 


A sequence of characters ending with a null character. 
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abs, 4-24 : eacces, 4-19 
acos, 4-26 eagain, 4-19 
Additive Operators, 2-3 ebadf, 4-19 
asin, 4-30 ebusy, 4-20 
atan, 4-31 | | echild, 4-19 
atan2, 4-32 ecvt, 4-49 
atof, 4-33 edom, 4-21 
atoi, 4-34 | eexist, 4-20 
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clearerr, 4-38 einval, 4-20 
close, 4-40 | eio, 4-18 
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enotty, 4-21 


enxio, 4-19 


eperm, 4-18 


epipe, 4-21 


erange, 4-21 


erofs, 4-21 

errno 
errno, 4-50 
Reporting Errors via 
errno, 4-18 


Error 

Check for I/O Error 
(ferror) Function, 4-72 

Error Returns, 4-18 

File Status Inquiry -- 
Clear Error Indicator 
(clearerr) Function, 4-38 

Number of Largest System 
Error Message (sys nerr) 
Function, 4-199 

System Error Message Number 
(errno) Function, 4-50 

System Error Messages 
(sys errlist) Function, 
4-198 


Errors 
Reporting Errors via errno, 
4-18 
Unix Errors, 4-18 
espipe, 4-21 
esrch, 4-18 
etxtbsy, 4-21 
exdev, 4-20 
exit, 4-63 
exp, 4-64 


Explicit Pointer Conversions, 
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fabs, 4-65 
fclose, 4-66 
fcvt, 4-69 
fdopen, 4-70 
feof, 4-71 
ferror, 4-72 
fflush, 4-73 
fgetc, 4-74 
fgets 
Gets Characters From a File 
(fgets) Function, 4-75 
Gets String From stdin File 
(fgets) Function, 4-110 
File Status Inquiry -- Clear 
Error Indicator (clearerr) 
Function, 4-38 
fileno, 4-76 
Float, 2-2 
Floor, 4-77 
fmod, 4-78 
fopen, 4-79 
fprintf, 4-80 
fputc, 4-85 
fputs, 4-86 
fread, 4-87 
free, 4-88 
freopen, 4-89 
frexp, 4-91 


fscanf, 4-92 
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getcwd, 4-102 isupper, 4-132 
getenv, 4-103 isxdigit, 4-133 
getgid, 4-104 kill, 4-134 
getlogin, 4-105 | ldexp, 4-135 
getopt, 4-106 Lexical Conventions, 2-1 
getpid, 4-109 Libraries 
Subroutines and Libraries, 
getuid, 4-111 | 4-15 
getw, 4-112 Library 
Multics C Standard Library 
Heap (Sorted by Name) (Tbl), 
Frees Heap Memory (free) 4-2 | 
Function, 4-88 System Calls and the 
Heap, 4-143 Runtime Library, 2-7 
Heap Management, 4-170 
Reallocates Heap Memory link, 4-136 


(realloc) Function, 4-164 , 
localtime, 4-138 
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memcpy, 4-149 
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memset, 4-150 
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C Compiler Diagnostic 
Messages (Tbl), A-2 
System Error Messages 
(sys errlist) Function, 
4-198 


mktemp, 4-151 
modf, 4-152 


Multics 

C Support of Multics File 
Types, 4-14 

Issue a Multics Command 
(system) Function, 4-197 

Multics C Routines (Sorted 
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4-7 

Multics C Standard Library 
(Sorted by Name) (Tbl), 
4-2 

Multics Trap Support of 
Unix Signals (Tbl), 4-16 


Null | 
Null Pointer (null), 4-15 
The Null Pointer Value, 2-7 
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Open a File (fdopen) 
Function, 4-70 

Open a File (fopen) 
Function, 4-79 
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Writing (open) Function, 
4-153 


Operators 
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sbrk, 4-165 

scanf, 4-166 

setbuf, 4-167 

setjmp, 4-168 
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sleep, 4-174 
sprintf, 4-175 
sqrt, 4-176 
srand, 4-177 
sscanf, 4-178 
stat, 4-179 
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stdout 
Puts Character On stdout 
File (putchar) Function, 
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tan, 4-200 
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Time | 
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ASCII (ctime) Function, 
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time, 4-202 
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